Merge upstream into your fork in GitHub

[Update: 12 August 2015: it is now possible to do this much more easily in the Beta version of GitHub Desktop]

For years I’ve been trying to get student assistants to use GitHub more effectively to work on larger projects.  One of the main problems though has been that the process of using forks + pull requests to submit their code to the main project has always required going back to the terminal for one key step: pulling and merging others’ changes from the upstream branches.  Today even for many seasoned programmers, the terminal/command prompt is a bit of a mystery to students.  Thus it would be great if the GitHub graphical client made this simple or at least possible.

The most recent versions of the GitHub client (at least on Mac; untested on Windows; I’m on v. 208) don’t exactly make the process simple, but at least they make it possible.

Open the GitHub client and if you haven’t worked on the project in a while, hit Sync. You should see your own fork; I’ll assume that you are working on the “master” branch and want to merge changes from the upstream (main project) master branch into your own branch.

Your screen should look something like this.  (I’ll be demoing on the amazing Latin dictionary program “whitakers-words”[*] which I do not have commit access on, so it’s like what my contributors to my projects would see).  All I’ve done is created a little demo text file.

Next I’ll pull down the tab on “master” and switch to the main developer’s master, “mk270/master” (third from bottom).


Click “Sync” in the upper left hand corner to copy it down.  The sync button will turn into a progress bar:

This actually creates a temporary branch confusingly called mscuthbert/mk270/master (or YOURNAME/THEIRNAME/BRANCH) but will just be displayed as mk270/master on the GitHub client.  No matter.  Now click the button next to the progress bar to create a pull request.  You will want to pull from this branch to your master branch (the one marked default branch):


You can leave the description blank since you’re just making a pull request to yourself. Go ahead and click “Send Pull Request”.

Click the link below the “Good work!” button to open up GitHub in your browser.  You should see something like this:

Scroll down to the bottom and you’ll see this.  Go ahead and click “Merge pull request” then “Confirm merge”.


Now you’ll see the option to delete this branch.  Go ahead and do it.  You are actually deleting “mscuthbert/mk270/master” not “mk270/master” — I hope it won’t let you delete the upstream master!

After doing so you’ll see this confirmation.

Now return to the GitHub client and switch back to “master” if it hasn’t already put you back there.

Go ahead and click “Sync” again for good measure.  Then you can check your History and see that you have all the most recent upstream commits:

Ta-da! Well, assuming that there aren’t any conflicts or anything of that sort.  In a case like that you’ll probably still need to get out the ol’ command-line tools, so you will still need to be a bit familiar with them (or have a friend who can help you out). Hopefully the next version of GitHub for Mac/Windows will make this much easier. But for day-to-day work, it’s now possible to stay in sync with the main repository on a more regular basis for people who use the graphic interface tools almost exclusively.

[*] edit August 10: EEK! Autocorrect originally changed “Whitaker’s Words” to “Whiskers-Words” — Fixed!  That app only does Cat-latin (catin?): "maumo, maumare, maumavi, maumatus  V (1st)     1 1 [GXXEK]   — meow;” not what we want!