Working with multiple upstream branches in Git

This is a quick reference to how I tend to work with different branches upstream, originally posted on my Blogger page. This may only apply to the Inkscape repo on GitLab.

Fork the project

First of all we need to fork the project. I'm going to explain this with the Inkscape Documentation repo, but it applies to the main repo and other places too.

  1. In the original project page, click on the Fork Button button at the top right of the page.
  2. Enter or edit the information. All of them can be changed, they won't affect the fork relationship between your forked repo and the upstream.
    Note: Be sure the "Branches to include" is set to "All branches". It's the default so you don't need to worry much.
  3. Click on the blue Fork Project button.

Clone the project to your local computer

Next we need to get the files to work on, so we'll clone the project down to our own computers.

  1. In the forked project page (where you're redirected to), click on the top-right blue button named Code.
  2. Copy the text under "Clone with SSH". When you click on the textbox the text should be automatically selected, so just press Ctrl+C.
  3. Open a terminal, navigate to your desired directory, then type git clone with a space after it, then press Ctrl+Shift+V to paste the copied direction into the terminal.
  4. Wait for the command to finish. After it does, enter cd <project name> to go into the project directory. In this case it's cd documentation.

Make sure branches are available

Now that we're in the project repo, the first thing is to make sure all the branches worked on are available. In the case of the Inkscape Docs repo, there are two branches that are supposed to be worked on, the master branch and the stable bugfix branch (as of writing it is "1.4.x"):

  1. Enter git branch to check if any branch is available. They shouldn't be at this point, and there is only a branch named "master".
  2. Next, type in git switch 1.4.x. It should switch normally, and you'd now have two branches: master and 1.4.x.

Feature branches

When doing anything to the branches, you won't want to do them directly on the branches themselves, as you would only develop one feature at a time this way, and it affects the ability to git pull (merge commits will pop up). That's why we should branch out first.

  1. Switch back to the master branch:

    git switch master

  2. Create a new branch based on the master branch: (here I used the name "master-zhtw" as the branch name, you can use anything you want)

    git switch -c master-zhtw

  3. Switch to the 1.4.x branch:

    git switch 1.4.x

  4. Create a branch based on the 1.4.x branch

    git switch -c 1.4.x-zhtw

Copying features between branches

Now that you have two branches: master-zhtw and 1.4.x-zhtw, you can develop features on one branch, then copy it to another. For this example I'm going to translate a string in the tutorials/basic/zh_TW.po po file, then copy it over to the 1.4.x-zhtw branch.

  1. Switch to the master-zhtw branch:

    git switch master-zhtw

  2. Edit a file and save it.

  3. Add the file:

    git add tutorials/basic/zh_TW.po

  4. Commit it:

    git commit -m "Small fix to the zh_TW basic tutorial translation"

The output of the last command looks like this:

[master-zhtw 4be38c66] Small fix to the zh_TW basic tutorial translation
 1 file changed, 3 insertions(+), 4 deletions(-)

Remember the number-alphabet combo beside the branch name, here 4be38c66. You can copy it to the clipboard, as we'll use it later.

Let's merge our changes into the 1.4.x-zhtw branch.

  1. Switch to the 1.4.x-zhtw branch:

    git switch 1.4.x-zhtw

  2. Cherry-pick the changes: (here replace 4be38c66 with what you copied previously)

    git cherry-pick 4be38c66

If the command succeeded (as it should), the changes are now in the 1.4.x-zhtw branch too.

Pushing both branches onto the fork project

The next step is to push both branches into your fork project on GitLab.

  1. Switch to master-zhtw:

    git switch master-zhtw

  2. Push with the upstream set: (because at this point there isn't a master-zhtw branch on our fork project, so we need to ask GitLab to create it)

    git push --set-upstream origin master-zhtw

  3. Switch to 1.4.x-zhtw:

    git switch 1.4.x-zhtw

  4. Push the changes:

    git push --set-upstream origin 1.4.x-zhtw

Making merge requests

Finally we're making merge requests to upstream our changes.

  1. Open or refresh your fork project page. You may see some hints to help you create merge requests.
  2. Switch to the master-zhtw branch with the top-left dropdown saying master. Click on it and select "master-zhtw".
  3. Press the top-right white button named Create merge request.
  4. Check the branch you're requesting to merge into. For this example if it says "inkscape/inkscape-docs/documentation:master", it is correct.
  5. Create the merge request with the blue Create merge request button.

Next, for 1.4.x:

  1. Go back to the fork project page.
  2. Switch to the 1.4.x-zhtw branch with the top-left dropdown saying master. Click on it and select "1.4.x-zhtw". 
  3. Press the top-right white button named Create merge request.
  4. Check the branch you're requesting to merge into. For this one you'd want to double check, since by default it'll want to merge into master, so you will need to click the blue link named "Change branches".
  5. In the page change the target branch from "master" to "1.4.x", then click on the button "Compare branches and continue".
  6. Click on Create merge request.

Congratulations, you just made MRs for your change on both branches.

— ltlnx 2024-11-07

標籤：隨想

如果想讓我知道您看過這個頁面，請點擊這個連結。運作原理。