Git Setup for Tracking Upstream

Starting from an Empty Repository#

I first created an empty repository on GitHub, then cloned it locally:

1
git clone https://github.com/YOU/YOUR-BLOG.git
2
cd YOUR-BLOG

Because the repository was empty, there was no main history to preserve. I created the clean template branch first:

1
git switch -c template

Then I added the source repository as upstream:

1
git remote add upstream https://github.com/AUTHOR/REPO.git

I only need to fetch from that remote. Disabling pushes adds a small guard against sending anything there by mistake:

1
git remote set-url --push upstream DISABLE

Now git remote -v should show something like this:

1
origin    https://github.com/YOU/YOUR-BLOG.git (fetch)
2
origin    https://github.com/YOU/YOUR-BLOG.git (push)
3
upstream  https://github.com/AUTHOR/REPO.git (fetch)
4
upstream  DISABLE (push)

Next, I fetched the upstream history and made template point to its default branch:

1
git fetch upstream
2
git reset --hard upstream/master

The upstream repository in this example uses master. If it uses main, the last command should be git reset --hard upstream/main instead.

There is no merge here. The local repository started empty, so template can simply begin at the same commit as upstream.

Creating the Working Branch#

With template in place, I created main from it:

1
git switch -c main

All personal changes belong on this branch.

I then pushed both branches to my own repository:

1
git push -u origin main
2
git push -u origin template

At this point, the branch roles are clear: template is the clean reference, while main is allowed to diverge.

Pulling Upstream Changes Later#

The update routine is:

1
git fetch upstream
2

3
git switch template
4
git reset --hard upstream/master
5

6
git switch main
7
git merge template
8

9
git push origin main
10
git push origin template

Using reset --hard on template is intentional. That branch should contain no personal work, so its job is to match upstream exactly.

It is still worth checking the current branch before running the reset:

1
git status --short --branch

If upstream has changed files that I also customised, the conflict happens when template is merged into main. That is where it belongs: the clean branch remains clean, and the decisions about my version stay on the working branch.

Why Keep the Extra Branch?#

It would be simpler to modify the template once and forget about upstream. For a small site, that may be entirely reasonable.

I kept the extra branch because it answers two useful questions:

• What did the original project change?
• What did I change on top of it?

The branch does not remove merge conflicts, but it makes their source much easier to understand.

A little structure now is cheaper than trying to remember the history six months later.