GitHub Fork & Pull Request Workflow

GitHub-Fork.md

Fork & Pull Request Workflow

Also know as Fork-and-Branch Workflow

Uses three repos:

• Original repository (remote) - An open source repo on GitHub
• Forked repository (remote) - my forked copy of the open source repo on Github
• Cloned (local) repository (from Forked) - my local copy of my forked repo

Summary

1. Fork a GitHub repository
2. Clone the forked repository to your local system.
3. Add a Git remote for the original repository.
4. Create a feature branch in which to place your changes.
5. Make your changes to the new branch.
6. Commit the changes to the branch.
7. Push the branch to GitHub.
8. Open a pull request from the new branch to the original repo.
9. Clean up after your pull request is merged.

Steps to complete Fork-and-Branch

1. Fork a repo

   • Click the fork icon in the upper right hand corner of your favorite repository.

2. Clone to desktop from forked repo

   # Use favorite desktop client or do from command line
   git clone https://github.com/james-priest/hello-world.git

3. Add upstream remote pointing back to the original repo

   # By convention this remote is named "upstream"
   git remote add upstream https://github.com/james-priest/hello-world.git

4. Sync cloned fork with upstream repo

   # fetch from upstream remote
   git fetch upstream
   
   # view all branches including local ones that represent remote ones (BTW, they are all local branches!)
   git branch -va
   
   # checkout master
   git checkout master
   
   # merge upstream (again, this is merging two local branches)
   git merge upstream/master

5. Create feature branch

   # new branch should be based off of master
   git checkout master
   
   # make it a simple, descriptive name & switch to it
   git branch newfeature
   git checkout newfeatue
   
   # ALTERNATE OPTION
   # combine previous two lines into one command if desired
   git checkout -b "newfeature"

6. Develop, test, and commit changes to feature branch

   # commit 1
   git commit -m "Add xyz"
   
   # commit 2
   git commit -m "Update xyz"
   
   # commit 3
   git commit -m "Expand xyz functionality"

7. CLEAN-UP BRANCH BEFORE PULL REQUEST

   If any commits have been made to the upstream master branch, you should rebase your feature branch so that merging it will be a simple fast-forward that won't require any conflict resolution work.

   1. Fetch upstream master & merge

      # Fetch upstream master and merge with your repo's master branch
      git fetch upstream
      git checkout master
      git merge upstream/master

   2. Rebase feature branch onto updated master

      # If there were any new commits, rebase your feature branch onto updated master
      git checkout newfeature
      git rebase master

   3. Now, it may be desirable to squash some of your smaller commits down into a small number of larger more cohesive commits. You can do this with an interactive rebase:

      # Rebase all commits on your feature branch
      git checkout
      git rebase -i master

      See the Interactive Rebasing section of Atlassian's Merging vs. Rebasing Tutorial

      See GitHub Help About Git rebase for a walkthrough on how to use git rebase -i

8. Push changes to GitHub

   # Pushes feature branch to GitHub
   git push origin newfeature

9. Initiate a Pull Request from feature branch

   1. Go to forked repo on GitHub
   2. Select feature branch
   3. Click the Pull Request button

10. CLEAN-UP REPOS AFTER INTEGRATION

    Once maintainer accepts and merges changes into original repositry

    1. Update local clone (git pull upstream master) - This brings down the updated master branch that includes your new developoment changes and merges it with local master

       # Checkout master
       git checkout master
       
       # Fetch upstream master and merge with local repo's master branch
       git fetch upstream
       git merge upstream/master
       
       # ALTERNATE OPTION
       # Update local clone (pull does a fetch & merge)
       git pull upstream master

    2. We can now delete the feature branch since changes are already in master branch

       # delete local branch
       git branch -d <branch name>

    3. Then we can update the master branch in the forked repository

       # push to my fork
       git push origin master

    4. Lastly, we push the deletion of the feature branch to forked repository

       # delete feature branch from my fork
       git push --delete origin <branch name>

Conclusion

Finally, I'm using git like a PRO! No more pulling my hair out.

References

This was put together with help from these two sources:

• GitHub Gist: Chaser324 / GitHub-Forking.md
• Scott Lowe Blog: Using the Fork-and-Branch Git Workflow