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 email@example.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.
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 firstname.lastname@example.org:jacobherrington/solidus.git (fetch) origin email@example.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 firstname.lastname@example.org: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.
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!
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. 🤠
You can also follow me on Twitter, where I make silly memes and talk about being a developer.