A Fool-Proof Way to Keep Your Fork Caught Up in Git

How do you keep a fork up to date with the main repository on GitHub?

It seems like quite a few people have asked me this over the last few months.

I'm not sure how many patterns there are for accomplishing this in git (I'd guess quite a few), but I have one that I use pretty much exclusively.

Let's identify why this is necessary, first. If you find an Open Source repository that you'd like to contribute to or keep a copy of, it's a common practice to fork that repository.

Forking a repository just means making a copy of it, presumably so that you can make changes to it without affecting the original repository. In many cases, that's because you don't have write access to the original repository.

On GitHub (where the term fork is commonly used) all you have to do is click the big fork button at the top of a repository. After a few seconds, you'll have your own copy of the original repository stored under your namespace.

If you intend to make changes to your fork, you'll most likely want to clone it to your local environment. For this article, I'll use my fork of the Solidus.io project (a project I help maintain on GitHub).

My fork is located at github.com/jacobherrington/solidus. To clone it to my local machine, I could run this git command:

git clone git@github.com:jacobherrington/solidus.git

Let's say I create this fork, clone it, then leave it alone for six months.

In six months, the original repository has changed substantially, and now my fork is outdated. The GitHub UI will give you an indication when this happens. That indication looks something like this:

So let's get it caught up.

1. Create a new remote

We are going to use the git remote command to do that! A remote is pretty simple; you can think of it as a bookmark that points to a remote repository.

For example, if I run git remote -v (the -v flag stands for verbose) in my local copy of the Solidus fork that I created, I'll see the default remote called origin and where it points:

$ git remote -v
origin    git@github.com:jacobherrington/solidus.git (fetch)
origin    git@github.com:jacobherrington/solidus.git (push)

You can see that there is a fetch and a push remote. You can ignore those for now, focus on the URL-looking thing. That's the same address we gave to git when we cloned the fork.

We can use this remote to pull in new code or push our changes up. If I run git push, my code is going to be pushed up to this remote by default.

However, you can specify another address when you are pushing or pulling. That's what we need to do to catch up our fork.

The first step is to create a new remote:

$ git remote add upstream git@github.com:solidusio/solidus.git

This command adds a new remote named upstream (you can choose a different name, but that's the one I prefer), pointing to the original repository on GitHub. That is, the repository that I originally forked from.

2. Pull in the new changes

Now that I've created a remote pointing at the original repo, which I like to call the upstream repository, I can easily pull in changes from that repository and push them to my fork.

First, I make sure that I'm on the master branch locally and that I don't have any weird local changes. (Careful copy-pasters, this will delete any work you have locally!)

$ git checkout master && git clean -fd

Then, I'll pull the changes from the upstream repository:

$ git pull upstream master
remote: Enumerating objects: 148, done.
remote: Counting objects: 100% (148/148), done.
remote: Total 186 (delta 148), reused 148 (delta 148), pack-reused 38
Receiving objects: 100% (186/186), 40.44 KiB | 20.22 MiB/s, done.
Resolving deltas: 100% (148/148), completed with 125 local objects.
From github.com:solidusio/solidus
 * branch                master     -> FETCH_HEAD
 * [new branch]          master     -> upstream/master
Updating 29acc0d0b..20973340b
Fast-forward
... # some files that changed
 87 files changed, 180 insertions(+), 177 deletions(-)

In this case, you can see I've picked up about 180 lines worth of changes. To update my remote fork (the repository on GitHub at jacobherrington/solidus), I'll need to push these changes up!

3. Push the changes up to your remote fork

As long as my local master branch hasn't actually diverged, it's this easy:

$ git push

You'll get some console feedback that looks something like this:

Total 0 (delta 0), reused 0 (delta 0)
To github.com:jacobherrington/solidus.git
   29acc0d0b..20973340b  master -> master

And now your remote fork is caught up with the original repository!

That's it. 🤠

There's more...

I'm writing a lot of articles these days, I run a podcast, and I've started sending out a newsletter digest about all of the awesome stories I'm hearing.

You can also follow me on Twitter, where I make silly memes and talk about being a developer.