Staying in sync with an upstream git repository
I’ve been writing software and maintaining my own web pages for decades. It sounds weird now that I wrote it like that, but I think I deployed my first non-public web pages in 2001 or 2002 on a kitchen server in the university’s dormitory, and bought my first own domain (unknown-artist.org, named after what Winamp would show if mp3 audio files did not have an ID3 tag) in 2004. Keeping up with dependencies has always been a challenge, and back in the day I’d use different folders, then CVS, then SVN, and finally git. Still a lot of manual diff’ing, and as that will likely never end, let’s try to make things as simple a possible.
But I’m also not doing this daily anymore, and git is complex, so if you’re updating your webpage only every six months or so, chances are you’re simply hoping to find the right commands in your command line history, and correctly recall what they’re doing. With git there are so many different ways to do so many different things. So I’m simply going to write down what works for me, mainly to have a place to always come back to and remember instead of solely relying on my command line history.
Initial setup
I’ll take the example of this blog itself. It is built on top of Eleventy Excellent a so called “Starter” (and an excellent one, not just because of the name) for 11ty (Eleventy), which is an amazing JS based static site generator.
I do not want to fork the repository, as I want to keep the specific webpage repository private, so I am going to duplicate it instead via git clone --bare to drop all remote references, git push --mirror it to my repo, and git remote add the original repository as an upstream remote back in. In my case this looks like this:
git clone --bare git@github.com:madrilene/eleventy-excellent.git
cd eleventy-excellent
git push --mirror git@github.com:krgr/my-webpage.git
cd ..
rm -rf eleventy-excellent.git
git clone git@github.com:krgr/my-webpage.git
git remote add upstream git@github.com:madrilene/eleventy-excellent.git
git fetch upstreamPlease use something meaningful instead of my-webpage, which is going to be a repository (in my case on github). Please also replace krgr as that is my github account. 😃
Catching up with upstream
Whenever there are changes to upstream that I want to add, I can run the following commands to fetch the newest updates and attempt a merge.
git fetch upstream
git merge upstream/mainIt depends a bit on how branches are handled by the respective maintainers, but for the example above, let’s assume you want to stay in sync with main. If there are no conflicts, the merge goes through neatly, and all I have to do is add a message for the commit. I then run a few quick checks locally to see if it builds and then compare the local version visually to the production version.
npm install
npm startIn case there are merge conflicts which can’t be automatically resolved, I go into the code and check what is up with that. I bias for defaulting to upstream because it keeps the complexity low. If a change in CSS upstream would for example be good enough for me to drop some of my local changes, I would accept it and rather reduce complexity instead of keeping changes around that have lost most of their value. Basically, I try to always have a very good reason for diverging from upstream. If I need to start over, I cancel the ongoing merge via git merge --abort.
After resolving all the conflicts, and having committed the changes, I compare the local version’s code holistically to the upstream version for a sense check. With the following command you can get a feeling for the delta between two versions, and if that delta only contains changes that really need to be there.
git diff main upstream/mainKeep on building.
