Using git submodules to have a portion of a website public

You can make one folder of a private website repo public by moving that folder to its own repository, then pulling it back in as a Git submodule. The parent repo stores a pointer to a specific commit of the public repo, and your host clones both at deploy time.

A submodule is a repository nested inside another repository. The parent doesn’t copy the files. It records the submodule’s URL and the exact commit to check out.

My setup

I recently created a new website on Netlify and I wanted to have a portion of that public on GitHub so anyone could submit a pull request for typos, etc.

I had a content folder in my Hugo repo, and the part I wanted to make public was a folder called handbook.

So I made a new repository for that, which I called handbook.

I removed the content/handbook folder I had in my parent repo (you don’t need this if you start fresh, but I wanted to move existing content):

rm -rf content/handbook

I committed the changes, then I added the submodule:

git submodule add https://github.com/flaviocopes/handbook

Note the https URL. Netlify can only clone public submodules over HTTPS without extra setup.

I deployed the website on Netlify and it automatically picked up the submodule.

The local editing problem

Now locally I had a problem, because it’s not like there’s a symlink to the submodule repository folder. The submodule is its own checkout, separate from where I actually edit the handbook content.

I removed the content/handbook folder and added a symlink from the local repo of the submodule:

# from within the `content` folder
ln -s ../../../dev/handbook/

Then I told Git to stop tracking the content/handbook folder using this command:

git update-index --skip-worktree content/handbook

(to restore tracking, use --no-skip-worktree instead)

In this way I had the best of both worlds - a submodule, but also - locally - a symlink to the submodule.

Things to watch out for

Anyone cloning the parent repo gets an empty content/handbook folder unless they clone with git clone --recursive, or run git submodule update --init after cloning.

The bigger gotcha: the parent repo is pinned to one commit of the submodule. Pushing new commits to the handbook repo does not update the website. You have to update the pointer too:

git submodule update --remote content/handbook

then commit and push the parent repo. Until you do, the site keeps building the old content, and it’s easy to spend ten minutes wondering why your fix isn’t live.