Activity: Use the GitHub Desktop client

Although most developers use the command line when working with version control systems, there are many GUI clients available that may simplify the whole process. GUI clients might be especially helpful when you’re trying to see what has changed in a file, since the GUI can easily highlight and indicate the changes taking place.

Follow a typical workflow with a GitHub project using GitHub Desktop

In this tutorial, you’ll use GitHub Desktop to manage the Git workflow.

  1. First, download and install GitHub Desktop. Launch the app and sign in. (You should already have a GitHub account from previous tutorials, but if not, create one.)
  2. Go to and browse to the wiki repository you created in the GitHub tutorial. (If you didn’t do the previous activity, just create a new repository.)
  3. Click Clone and select Open in Desktop. (In the confirmation dialog, select Open in GitHub

    Open in GitHub Desktop

    GitHub Desktop should launch with a “Clone a Repository” dialog box about where to clone the repository. If desired, you can change the Local Path.

  4. Click Clone.

    Clone a Repository

  5. Go into the repository where GitHub Desktop cloned the repo (use your Finder or browsing folders normally) and add a simple text file with some content. Or make a change to an existing file.
  6. Go back to GitHub Desktop. You’ll see the new file you added in the list of uncommitted changes on the left.

    Uncommitted changes shown

    In the list of changed files, the green + means you’ve added a new file. The yellow circle means you’ve modified an existing file.

  7. In the lower-left corner of the GitHub Desktop client (where it says “Summary” and “Description”), type a commit message, and then click Commit to Master.

    When you commit the changes, the left pane no longer shows the list of uncommitted changes. However, you’ve committed the changes only locally. You still have to push the commit to the remote (origin) repository.

  8. Click Push origin at the top.

If you view your repository online (by going to Repository > View on GitHub), you’ll see that the change you made has been pushed to the master branch on origin. You can also click the History tab in the GitHub Desktop client (instead of the Changes tab), or go to View > Show History to see the changes you previously committed.

Although I prefer to use the terminal instead of the GitHub Desktop GUI, the GUI gives you an easier visual experience to see the changes made to a repository. You can use both the command line and Desktop client in combination, if you want.

Create a branch

Now let’s create a branch, make some changes, and see how the changes are specific to that branch.

  1. Go to Branch > New Branch and create a new branch. Call it “development” branch.

    When you create the branch, you’ll see the Current branch drop-down menu indicate that you’re working in that branch. Creating a branch copies the existing content (from the branch you’re currently in, master) into the new branch (development).

    Working in a branch

  2. In your new branch, browse to the file you created earlier and make a change to it, such as adding a new line with some text. Save the changes.
  3. Return to GitHub Desktop and notice that on the Changes tab, you have new modified files.

    New files modified

    The file changes shows deleted lines in red and new lines in green. The colors help you see what changed.

  4. Commit the changes using the options in the lower-left corner, and click Commit to development.

  5. Click Publish branch to make the local branch also available on origin (GitHub). (There are usually two versions of a branch — the local version and the remote version.)

  6. Switch back to your master branch and note how the changes you made while editing in the development branch don’t appear in your master branch.

    Usually, you create a new branch when you’re making extensive changes to your content. For example, suppose you want to revamp a section (“Section X”) in your docs. However, you might want to publish other updates before publishing the extensive changes in Section X. If you were working in the same branch, it would be difficult to selectively push updates on a few files outside of Section X without pushing updates you’ve made to files in Section X as well.

    Through branching, you can confine your changes to a specific version that you don’t push live until you’re ready to merge the changes into your master branch.

Merge the development branch into master

Now let’s merge the development branch into the master branch.

  1. In the GitHub Desktop client, select the development branch. Make a change to a file, and then commit the changes.
  2. Switch to the master branch.
  3. Go to Branch > Merge into Current Branch.
  4. In the merge window, select the development branch, and then click Merge into master.

    Merging into master

    If you look at your changed file, you should see the changes in the master branch.

Merge the branch through a pull request

Now let’s merge the development branch into the master using a pull request workflow. We’ll pretend that we’ve cloned a repo managed by engineers, and we want to have the engineers merge in the development branch. (In other words, we might not have rights to merge branches into the master.) To do this, we’ll create a pull request.

  1. As before, switch to the development branch, make some updates to the content in a file, and then save and commit the changes. After committing the changes, click Push origin to push your changes to the remote version of the development branch on GitHub.
  2. In the GitHub Desktop client, while you have development branch selected, go to Branch > Create Pull Request.

    GitHub opens in the browser with the Pull Request form opened.

    Pull reqeust

    The left-facing arrow from the development branch towards the master indicates that the pull request (“PR”) wants to merge development into master.

  3. Describe the pull request, and then click Send Pull Request.

    At this point, engineers would get an email request asking for them to merge in the edits. Play the part of the engineer by confirming the merge request. As long as the merge request doesn’t pose any conflicts, you’ll see a Merge Pull Request button.

    Confirm merge request

    To see what changes you’re merging into master, you can click the Files changed tab. Then click Merge Pull Request to merge in the branch, and click Confirm Merge to complete the merge.

  4. Now let’s get the updates you merged into master online into your local copy. In your GitHub Desktop GUI client, select the master branch, and then click the Fetch origin button. Fetch gets the latest updates from origin but doesn’t update your local working copy with the changes.

    After you click Fetch origin, the button changes to Pull Origin.

  5. Click Pull Origin to update your local working copy with the fetched updates.

    Now check your files and notice that the updates that were originally in the development branch now appear in master.

Managing merge conflicts

Suppose you make a change on your local copy of a file in the repository, and someone else changes the same file using the online browser interface. The changes conflict with each other. What happens?

When you click Push origin from the GitHub Desktop client, you’ll see a message saying that the repository has been updated since you last pulled:

“The repository has been updated since you last pulled. Try pulling before pushing.”

The button that previously said “Push origin” now says “Pull origin.” Click Pull origin. You now get another error message that says,

“We found some conflicts while trying to merge. Please resolve the conflicts and commit the changes.”

If you decide to commit your changes, you’ll see a message that says:

“Please resolve all conflicted files, commit, and then try syncing again.”

The GitHub Desktop client displays an exclamation mark next to files with merge conflicts. Open up a conflict file and look for the conflict markers (<<<<<<< and >>>>>>>). For example, you might see this:

<<<<<<< HEAD
this is an edit i made locally.
this is an edit i made from the browser.
>>>>>>> c163ead57f6793678dd41b5efeef372d9bd81035

(From the command line, you can also run git status to see which files have conflicts.) The content in HEAD shows your local changes. The content below the ======= shows changes made by elsewhere.

Fix all the conflicts by adjusting the content between the content markers and then deleting the content markers. For example, update the content to this:

this is an edit i made locally.

Now you need to re-add the file to Git again. In the GitHub Desktop client, commit your changes to the updated files. Then click Push origin. The updates on your local get pushed to the remote without any more conflicts.

51% Complete

51/94 pages complete. Only 43 more pages to go...


If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285