This tutorial assumes a basic understanding of git. Including creating branches, adding / committing code, and creating pull requests.
Prior to my current role, my workflow while working with git typically looked something like this:
- Clone the repo.
- Ensure the local master is update to date, then create a branch off of master and start coding.
- Add, commit, and push up the branch.
- Check for any merge conflicts or unintended changes. Then, create a pull request for review.
- Rinse and repeat, starting with step 2.
In my current role, we use a pattern that is commonly used when contributing to an open source project. It uses two concepts that were not included in the previous workflow example, forks and remotes.
When working with a project that you do not maintain, you likely don't have the necessary credentials to push changes directly to that repo. This is where forking comes in. You can make a copy of the repo onto our personal account and make all the changes you want, without affecting the original repo.
After you make this copy (fork) of the repo, this new location is where you will be pushing your changes. The original repo and your copy are in different locations, aka remotes.
(In case you'd like to skip the more thorough explanation)
- Fork the repo to your desired account.
- Clone the forked repo locally.
- Add a remote that points to the original repo and name it
- Manually sync up with
get fetch upstreamfollowed by
git statusto take a look.
- If necessary, pull in any changes.
- Create a branch off of master and start coding.
- Add, commit, and push up the branch (to your fork).
- Check for any merge conflicts or unintended changes between your branch and the original repo's master branch. If it looks good, create a pull request.
- Rinse and repeat, starting with step 4.
- Fork the repo you'll be working with to your desired account.
Clone your forked repo locally by running
git clone https://github.com/your-username/name-of-repo.git
- Navigate to your new repo with
git status && git remote -vin your terminal and you will see the following:
On branch master Your branch is up to date with 'origin/master'. nothing to commit, working tree clean origin https://github.com/your-username/name-of-repo.git (fetch) origin https://github.com/your-username/name-of-repo.git (push)
Notice that the name
originis auto-generated and points at your
fork of the repo. When you make new changes to the code base,
originis where you will push them. Eventually, the original repo will have changes made to it, so you need a way to pull in these updates. In order to do so, you need to add a remote that points to it. Traditionally, we call this
git remote add upstream https://github.com/not-your-username/name-of-repo.git. Then
git status && git remote -vonce again to see the newly added remote and its location.
origin https://github.com/your-username/name-of-repo.git (fetch) origin https://github.com/your-username/name-of-repo.git (push) upstream https://github.com/not-your-username/name-of-repo.git (fetch) upstream https://github.com/not-your-username/name-of-repo.git (push)
- Next, we need to manually sync up with
upstreamby reaching out to it. To do this, run
git fetch upstream. After that, if you run
git status, it still says:
On branch master Your branch is up to date with 'origin/master'.
- Let's resolve this by ensuring our local master is pointing to
upstream's master. Run
git branch --set-upstream-to=upstream/master masterand then
git statusonce again. Since this has been recently cloned, no changes are likely, so you should see something like this:
On branch master Your branch is up to date with 'upstream/master'.
- Now that this this is setup, if your branch were to fall out of date, you can simply run
git pull, to pull in any changes.
- Additionally, I use a tool called Spaceship Prompt, as it gives me some helpful visual representations of the status of my master branch, among many other features.
- Now that we know our local master is up to date, create a branch off of master and start coding.
- After you have successfully completed your changes and run any necessary tests, you can add and commit your work.
- Once you are ready to push up your changes, remember to push them to your forked repo. The command will look something like,
git push origin feature-branch.
- Once you see your branch appear in GitHub, be sure to compare your branch with the original repo's master branch. This is where you can check for any merge conflicts that need to be resolved or any changes that perhaps you didn't intend to make. If it all looks good, make your pull request.
I hope this was helpful to you. Please feel free to reach out if you have questions or suggestions on how to improve this tutorial, or leave a comment below. You can also find me on Twitter.
I'd like to credit Kent C Dodds's tutorial on egghead.io called How to Contribute to an Open Source Project on GitHub as well as the Pro Git book written by Scott Chacon and Ben Straub. The GitHub - Contributing to a Project chapter was particularly helpful. They were both great resources when putting this together and I highly suggest checking them out if you are looking for more information.