When I first started contributing to projects on GitHub, I had a difficult time with keeping my work and the original project in sync. Eventually, I found a way that works for me.
Step 1: Fork the Repository
I do this with the GitHub fork button. As an example, if I wanted to contribute to https://github.com/pjreddie/darknet, I would fork it resulting in my own copy at https://github.com/salcode/darknet.
Step 2: Clone My Repository Locally
At this point, I make a copy of my repository locally with the command.
git clone git@github.com:salcode/darknet.git
and then I move into the project directory with
cd darknet/
Step 3: Add the Upstream Repository
Now we have my GitHub repository associated with my local install as origin
. I can double-check this by running
git remote -v
To add the upstream repository (pjreddie/darknet), I can run
git remote add upstream git@github.com:pjreddie/darknet.git
Now when I run git remote -v
, I see both my origin
remote and the upstream
remote.
Step 4: Work on a New Branch
The key for me in the whole process is to never work on a branch that appears on the upstream
remote. In this case the only branch on upstream
is master
. So I’m going to create a new branch by copying master
, I’ll prefix my branch name with my initials and include the relevant issue number at the end of the branch whenever possible.
git checkout -b sf/improve-image-detection-22
Now, I do all of my work in the sf/improve-image-detection-22
branch.
Step 5: Keeping Up To Date with Upstream Changes
The original project will continue to change as I work on my own code. To bring those changes into my local branch I do the following.
# Update the `master` branch to match the current `upstream/master`
git checkout master
git pull upstream master
# Bring the changes in master into my current branch
git checkout sf/improve-image-detection-22
git rebase master
At this point, my branch sf/improve-image-detection-22
should have all of the commits from upstream/master
with my commits added as the most recent commits.
Step 6: Create a Pull Request
After pushing my branch to my GitHub repository
# Push my branch to https://github.com/salcode/darknet
git checkout sf/improve-image-detection-22
git push
I can go to the original repository in my browser (pjreddie/darknet) and GitHub will allow me to create a Pull Request (PR).
Depending on how soon the original author reviews my PR, I may need to “refresh” my PR by repeating steps 5 and 6.
Leave a Reply