Keeping a Fork in Sync with the Original
While opensource projects are meant to allow contributors to create modifications and submit those modifications back upstream, the process for doing so isn't always clear. In a rapidly changing source repo, making a fork and keeping that fork in sync with the upstream (original repo) just so that you can submit a pull request can be tricky if one doesn't know about a few tricks. This article explains one of those tricks in keeping a copy of the
upstream repo as the
master branch locally on your PC while your new
feature branches pointed at your
forked repo.
Step 1 - Fork the Original Repo
Most open source projects do not allow you to create a branch in the master project, which requires contributors to fork the original repo so that you can make changes there first before submitting the change to the upstream repo in the form of a pull request. The first step is to of course fork the original repo. In GitHub, this can be done by clicking on the Fork icon at the top of the open source project you are working with.
Step 2 - Clone the Original Repo to Your PC
Once the fork is created, its time to clone this or the upstream repo to your PC so that you can create a new branch and begin editing the source code. The clone can be done from either the fork or the upstream repo. Either will work as we rebase-ing the fork with the upstream on a regular basis.
git clone [your clone URL here]
# assuming the clone was the upstream do the following to rename it to upstream
git remote rename origin upstream
Step 3 - Point Master Branch to Upstream
Now that we renamed the origin to upstream, we need to ensure that the master branch we obtained still points at this upstream repo (and not our fork). this is done by:
git branch -avv # existing branches like master are linked to upstream/xxx
Step 4 - Add the Fork URL as a new Remote
Now we need to add back in a new origin pointing at our fork so that all of our new branches point back to the fork and not the upstream repo.
git remote add origin [your fork URL here]
Step 5 (Option a) - Checkout a new Feature Branch (For New Branch in Fork)
Now we have our two remote created, we simply checkout a new feature branch to begin our work.
git checkout -b [Your Feature Branch Name]
Step 5 (Option b) - Pull and Checkout Feature Branch (For Existing Branch in Fork)
If you already have a feature branch in the Fork, we'll need to pull it to our local machine before we begin our work.
git pull origin [Your Feature Branch Name]
git checkout [Your Feature Branch Name]
Step 6 - Rebase Master
Now before any commits are completed, you will need to synchronize the master with the upstream repo and rebase our fork to the latest changes in that parent repo. Since we aren't making changes directly on master anyway in our fork, we will be using the Rebase command, which ignores any changes in master on your PC and will replace it with what is checked out from the upstream repo.
# switch to the master branch
git checkout master
# pull recent updates from upstream
git pull upstream master
# switch back to your forked-based feature branch
git checkout [Your Feature Branch Name]
# rebase the fork's master branch with the upstream master
git rebase master
# push the rebased master back up to our fork living in our fork remote
git push origin master --force
Step 7 - Commit and Push Changes to Fork
Assuming the changes are complete and the above step was completed moments before this step, just commit the code changes you made and push them to the fork.
git push origin [Your Feature Branch Name]
Step 8 - Submit Pull Request
As you return to GitHub or whatever cloud-based git repo you are using, submit your pull request to the upstream owners for their review and inclusion in a future version of their code. It's good form to do this as quickly as possible in order to avoid any chances of significant code changes coming into play before the pull request is reviewed.
Update 5/29/19: Adding descriptive/instructional link to rebase step.
Update 6/20/19: Adding Option a and b for Step 5
