Quick hacks on GitHub Pages

July 08, 2023

Today's topic is a quick note on a kind of trivial problem. Suppose you've written some small web project and you'd like to publish it online somewhere. GitHub Pages is the feature where they will put a web server in front of a branch of your repository.

The problem you'll soon discover is that Git isn't so happy about switching between branches that contain unrelated code. Suppose you check out your main branch and build index.js. If you then try to check out your pages branch with the intent of checking in that file for publishing, it will conflict with the existing index.js. You can solve this with multiple checkouts of the repository in different directories, but it's clunky to set it up twice.

So here's the trick: git worktree is the tool for managing a second checkout of a single Git repository. Set it up like this:

# create a 'pages' worktree:
$ git worktree add pages
$ cd pages

# create an empty 'pages' branch:
$ git switch --orphan pages

$ ...create files, commit...
$ git push -u origin pages

From now on, to deploy your code to GitHub pages, you just copy it to the 'pages' subdir, then commit and push. I typically write a script for it so I don't need to remember what to do when I move between projects.

PS: That above script in particular is used to deploy this little data explorer of the relative sizes of US states and EU countries. Ireland is surprisingly close to South Carolina in both land area and population!