Convert Hugo Theme to Submodule

December 11, 2025

The problem

I develop the site locally and push its built /public directory to a VPS. Currently the entire directory for the site, including the themes directory, is under git version control. I’m wanting to make some changes to the theme on a git branch other than the master branch, while still being able to create new posts that get committed to the main branch. Technically that could be done with the current setup, but it would be easier if the theme was a git submodule.

Note that I’m reluctant to rely on LLMs for coding. I do rely on them for this kind of thing though. Mostly because I don’t find it very interesting. I still proceed with caution though.

Initialize a git repo in the theme directory

cd themes/zalgorithm
git init
git add .
git commit -m "initial commit"

Push the theme to its own GitHub repo

git remote add https://github.com/scossar/zalgorithm_theme
git push -u origin master
cd ../.. # back to root directory

Remove theme from main repo and add as submodule

git rm -r --cached themes/zalgorithm

rm -rf themes/zalgorithm  # probably back it up first

# pulls the theme back, now as a submodule
git submodule add https://github.com/scossar/zalgorithm_theme themes/zalgorithm

git add .gitmodules themes/zalgorithm
git commit -m "convert theme to submodule"

Working with the theme submodule

cd themes/zalgorithm
git checkout -b new-feature
# make changes
git add .
git commit -m "new features"
git push origin new-feature

To use the new feature (this seems wrong, but will confirm soon):

cd themes/zalgorithm
git checkout master
git pull
cd ../..
git add themes/zalgorithm
git commit -m "update theme to latest version"

Won’t the current state of the local theme directory get used, regardless of how it’s synced with the repo?

About .gitmodules

❯ cat .gitmodules
[submodule "themes/ananke"]
        path = themes/ananke
        url = https://github.com/theNewDynamic/gohugo-theme-ananke.git
[submodule "themes/zalgorithm"]
        path = themes/zalgorithm
        url = https://github.com/scossar/zalgorithm_theme

.gitmodules is a configuration file that git uses to track a repo’s submodules.

[submodule "themes/zalgorithm] is the section header for the theme’s submodule
path is the path to the submodule in the blog’s directory structure
url is the remote URL

.gitmodules is version controlled, so it’s committed to the repo. Submodules can be pulled in when the repo is cloned:

# note: the main blog repo is private, although the blog is public, so what's the point of that?
git clone --recurse-submodules <zalgorithm blog repo>

If the repo is already cloned, submodules can be pulled in with:

git submodule update --init --recursive

Changing the submodule’s URL

Edit .gitmodules manually or:

git config --file=.gitmodules submodule.themes/zalgorithm <new URL>

# sync the changes
git submodule sync
git submodule update --init --recursive

Note (supposedly) git/config isn’t tracked by git. .gitmodules is tracked by git. (Confirm this if it’s important.)

Different forms of URLs for GitHub

Using HTTPS (e.g.https://github.com/scossar/zalgorithm_theme) requires the use of username/password or personal access token.

Using git@github.com:... uses SSH keys. No need for password prompts once keys are setup.

Tags:

Code