Quick Tip: Sync a GitHub Fork via the Command Line

    Shaumik Daityari

    When you fork someone’s repository on GitHub, you’ll want to update your fork with any changes made to the original. There are various ways to do this. In this quick tip, Shaumik describes how to update your fork via the command line. Another option is to update your fork via the GitHub web interface.

    Git is a distributed version control system, which means that each copy of a repository is complete with its own history. GitHub, on the other hand, is an online collection of Git repositories. GitHub introduces the concept of forking, which involves making a copy of the main repository.

    GitHub Workflow

    GitHub workflow

    To understand the concept of updating a fork, one must first know why this is necessary.

    An organization can’t grant every potential contributor write access to its main repository, so the public can only view the central repository. A fork is a copy of this repository that a user can create. Users have read and write access to their own forks.

    Normally, programming happens on a local machine (or a VM) instead of the GitHub interface directly, so a clone of the fork will normally be created.

    Once a contributor has made a commit to a local copy, it then needs to be pushed to the fork on GitHub (which is possible due to the write access). Then, a pull request is created from the fork to the central repository.

    Keeping Your Fork Up to Date

    When the central repository is updated with someone else’s code (after the fork was created), these new commits do not magically appear on the fork. One must first download and merge these changes with the local repository, and then push it to the fork.

    For legacy reasons, in our local repository, we name the central repository remote as upstream and the fork as origin.

    Ideally, you should never make any commits directly to the master branch of your fork or the local repository. This branch must only be used for keeping the updated code from upstream. All changes must be made to new feature or bug branches, and pushed to the branches with the same name on the fork.

    Hence, the following steps help in updating the fork with the latest commits from the central repository:

    • Pull from upstream’s master branch to local repository’s master
    • Push from local repository’s master to fork’s master

    These steps assume that you have forked the repository and cloned the fork on your local machine.

    For demonstration, we’ll be using the repository of e-Cidadania on GitHub.

    Step 1: Fork the Repository

    To fork a repository, you need to click the fork button (top right part of the screenshot).

    e-Cidadania's home page on GitHub

    e-Cidadania's home page on GitHub

    Step 2: Clone Your Forked Repository

    To clone your fork, you first need to select the protocol from the dropdown (as shown in the screenshot below) and copy the link. We’ll select the SSH protocol in this demonstration:

    e-Cidadania's fork on your profile

    e-Cidadania's fork on your profile

    Open the terminal and run the following command:

    git clone git@github.com:sdaityari/e-cidadania.git

    You then need to link your local repository to the central repository to be able to pull changes from the central repository. This is done by adding the upstream remote. First, copy the SSH link from the central repository, and add the remote by running the following command:

    git remote add upstream git@github.com:cidadania/e-cidadania.git

    To verify that the remote has been added, check the list of remotes by running the following command:

    git remote -v

    The output should be as follows:

    origin  git@github.com:sdaityari/e-cidadania.git (fetch)
    origin  git@github.com:sdaityari/e-cidadania.git (push)
    upstream    git@github.com:cidadania/e-cidadania.git (fetch)
    upstream    git@github.com:cidadania/e-cidadania.git (push)

    Step 4: Pull Changes from upstream (Central Repository)

    When there are new commits in the central repository’s master, which are not present in your fork, you get a message from GitHub on the fork’s page. In the screenshot, you can see the message which says This branch is 36 commits behind cidadania:master:

    Fork’s page on GitHub

    Fork’s page on GitHub

    To pull these changes onto your local repository, run the following command:

    git pull upstream master

    This command updates your master branch from the upstream remote.

    Step 5: Push Changes to origin (Fork)

    To push these updates from the central repository to the fork, simply run the following:

    git push origin master
    Counting objects: 739, done.
    Delta compression using up to 4 threads.
    Compressing objects: 100% (381/381), done.
    Writing objects: 100% (739/739), 219.66 KiB | 0 bytes/s, done.
    Total 739 (delta 408), reused 602 (delta 278)
    To git@github.com:sdaityari/e-cidadania.git
       da546f3..2fc7f31  master -> master

    To confirm that the changes have been updated, visit the fork’s page on GitHub again!

    Fork's updated page on GitHub

    Fork's updated page on GitHub

    The message This branch is even with cidadania:master shows that the commits have been added to the fork’s master branch.