GitHub Fork, Branch & Pull Workflow

fork_pull.md

The Fork & Pull Workflow

The fork and pull workflow is necessary for effectively and efficiently contributing to and collaborating on open-source work. This gist describes the workflow for contributing to an open-source project for which you don't have write access. It is an adaptation from a post on my website here.

• The Short Version
• The Long Version

The Short Version

1. Fork the GitHub repository.
2. Clone locally: git clone https://github.com/user/repo.git.
3. Add "upstream" remote: git remote add upstream https://github.com/user/repo.git
4. Create local dev branch: git checkout -b new_feature
5. Make changes on branch until ready to push to "upstream" repo.
6. Push branch to remote: git push origin new_feature
7. Pull from "upstream" repo into master: git checkout master, git pull upstream master
8. Sync any changes with dev branch: git checkout new_feature, git merge master
9. Open Pull request on GitHub (dev branch to "upstream")
10. Once Pull request accepted, update your fork: git checkout master, git pull upstream master
11. Delete dev branch on GitHub, or locally with: git branch -d new_feature, git push origin --delete new_feature

The Long Version

1. Fork the GitHub repository you want to work on by navigating to the repository on GitHub and clicking the "Fork" button.
2. Clone the repository locally: git clone https://github.com/user/repo.git.
3. Add remote called “upstream” pointing to the original repository: git remote add upstream https://github.com/user/repo.git. As the developers of the upstream (original) repo may be making changes as you work on your version of the repo, we need this upstream remote so that we can periodically pull any new changes.
4. In your locally cloned repo, create a new development branch to work on (here called “new_feature”): git checkout -b new_feature
5. Make any changes you want in this branch and be sure to push changes to the remote as necessary.
6. Push your local branch to your remote repository: git push origin new_feature.
7. When you're done with your changes and ready to push your changes to the upstream (original) repo, we should first pull any changes in the upstream (original) repo to our forked version by going back to the master branch: git checkout master, and then pulling changes: git pull upstream master
8. Go back to your development branch and merge in these changes (if any): git checkout new_feature, and then git merge master
9. Now you're ready to open a pull request on GitHub merging your changes with the upstream (original) repository.
10. Once the pull request is accepted, you’ll want to pull those changes into your forked-version of the repository (so that it's up-to-date). Change to master: git checkout master and pull: git pull upstream master.
11. Delete your feature branch using the GitHub website or, delete the local branch: git branch -d new_feature, and delete then the remote: git push origin --delete new_feature.