GitHub Desktop is a great tool for different collaborative development models. In this article we will be walking through using GitHub Desktop with the ‘fork and pull’ model. This model can be used within an organization you belong to that contains a private repository you do not have push access to but need to commit changes to, or within an open source project that you would like to contribute to. You can read this guide for more information about contributing to open source projects.
A note about the conventions used in this article:
- We will be using the
masterbranch when referring to the default branch of the repository. This can sometimes have a different name, like
upstreamrepository refers to the parent repository of the fork we are creating. When we use the convention
upstream/masterwe are referring to the
masterbranch of the
- Create a fork of the repository you would like to contribute to.
The first step you will need to take is to create a fork of the repository that you would like to contribute to. You can follow GitHub’s guide on how to fork a repository for more information about that process.
- Clone your newly created fork to GitHub Desktop.
You can either clone your newly created fork directly from GitHub to GitHub Desktop using the green
Clone or download button on the repository’s page, or directly within GitHub Desktop by going to the file menu and selecting
- Create a new
topicbranch in GitHub Desktop.
Git has a branching model that makes it easy to quickly create lightweight topic branches. Topic branches are created to implement a specific change, like a feature or bugfix. Create a new branch in GitHub Desktop from the branch dropdown with the appropriate title for the change that you are going to make. Creating topic branches like this helps ensure that the
master branch only has code in it that you will eventually want to merge back into the
- Review and commit your changes.
This is your time to contribute. Start making your changes in your favorite text editor or integrated development environment (IDE). GitHub Desktop supports a number of text editors, which means you can conveniently open your repository directly in your editor of choice without even needing to switch applications. When you have made some progress, commit those changes using GitHub Desktop.
Some notes about committing:
- Did you make a large number of changes to a file but only want to commit a portion of those changes? GitHub Desktop supports partial commits), which allows you to create multiple meaningful commits.
- Did you accidentally make changes that you no longer want to commit? GitHub Desktop lets you quickly discard specific changes to files. If you need to recover discarded changes they can be found in the Recycle Bin (Windows) or Trash (macOS).
- Merge your
topicbranch back into the
Now that you have finished creating commits in your
topic branch you are ready to merge them back into your
master branch. Switch back to your
master branch, select
Compare to Branch from the file menu, and choose your
topic branch from the branch list. GitHub Desktop will notify you of any merge conflicts, which you can then resolve in your text editor before merging.
- Check for any new commits that have been made in the
You are almost ready to submit a pull request to the
upstream/master branch. First, you will want to make sure that there are no new changes that have been pushed to
upstream/master that you need to merge into the
master branch of your fork.
Fetch originin GitHub Desktop to fetch any new changes from the remote repositories (even though it only says
Fetch originGitHub Desktop will fetch from both the
upstreamremotes in this instance).
- Go to the
Historytab and in the
Select Branch to Comparebox choose
- If everything is up-to-date then you can proceed to step 7.
- If there are new commits available to merge click
Merge into masterto merge the changes from the
upstream/masterbranch into your local
masterbranch. GitHub Desktop will again let you know if there are any merge conflicts that need to be resolved.
master branch is now up-to-date with
upstream/master, and you are ready to submit your pull request.
- Submit your pull request.
You can begin the the process of creating a pull request within GitHub Desktop by going to the menu and selecting
Create Pull Request. This will launch your default browser and and take you directly to the page on GitHub where you can open a pull request.
- Make any additional changes requested for your pull request.
The next step in the process is for a maintainer of the upstream repository to review your pull request. They may suggest some changes for you to make, and you can use GitHub Desktop to commit those changes and push them up to the
master branch of your fork. Your pull request will automatically be updated to reflect the new commits that have been pushed.
You may also be asked to resolve merge conflicts if new changes that conflict with your proposed changes have been introduced since your pull request was opened. Simple merge conflicts that are caused by competing line changes can be resolved directly on GitHub, but more complex merge conflicts will need to be resolved locally on your machine.
- Your pull request gets merged!
Congratulations! Your pull request has been approved and merged. Enjoy that lovely green square on your contributions graph and go ahead and find the next bug to squash.