Working with multiple upstream branches in Git
This will be eventually expanded, but for now it's just a quick reference to how I tend to work with different branches upstream. 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.
- In the original project page, click on the button at the top right of the page.
- 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. - Click on the blue 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.
- In the forked project page (where you're redirected to), click on the top-right blue button named .
- Copy the text under "Clone with SSH". When you click on the textbox the text should be automatically selected, so just press Ctrl+C.
- 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. - Wait for the command to finish. After it does, enter
cd <project name>
to go into the project directory. In this case it'scd 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"):
- 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". - 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.
- Switch back to the master branch:
git switch master
- 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
- Switch to the 1.4.x branch:
git switch 1.4.x
- 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.
- Switch to the
master-zhtw
branch:
git switch master-zhtw
- Edit a file and save it.
- Add the file:
git add tutorials/basic/zh_TW.po
- 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.
- Switch to the 1.4.x-zhtw branch:
git switch 1.4.x-zhtw
- 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.
- Switch to master-zhtw:
git switch master-zhtw
- 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
- Switch to 1.4.x-zhtw:
git switch 1.4.x-zhtw
- 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.
- Open or refresh your fork project page. You may see some hints to help you create merge requests.
- Switch to the master-zhtw branch with the top-left dropdown saying . Click on it and select "master-zhtw".
- Press the top-right white button named .
- Check the branch you're requesting to merge into. For this example if it says "
inkscape/inkscape-docs/documentation:master"
, it is correct. - Create the merge request with the blue button.
Next, for 1.4.x:
- Go back to the fork project page.
- Switch to the 1.4.x-zhtw branch with the top-left dropdown saying . Click on it and select "1.4.x-zhtw".
- Press the top-right white button named .
- 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". - In the page change the target branch from "master" to "1.4.x", then click on the button "Compare branches and continue".
- Click on .
Congratulations, you just made MRs for your change on both branches.
— ltlnx 2024-11-07
Comments
Post a Comment
All comments are moderated. If your comment doesn't show up within 14 days, please send me an e-mail.