Hugo Git Submodule Extraction Pattern

Fri, 01 May 2026 00:00:00 +0000

Hugo Git Submodule Extraction Pattern#

What Was Established#

Hugo themes installed as Git submodules (e.g., git submodule add <url> themes/theme-name) carry their own Git history. When you want to customize the theme beyond configuration, extracting the submodule into the main repository gives you full control over theme files without managing a separate submodule repository.

The Pattern#

Remove the submodule registration:

git submodule deinit themes/theme-name
git rm themes/theme-name

Re-add the theme as regular files:

git clone <theme-url> /tmp/theme-temp
cp -r /tmp/theme-temp/* themes/theme-name/
git add themes/theme-name/
git commit -m "Extract theme-name from submodule into main repo"

Result: Theme files are now tracked directly in the main repository.

When to Use#

You need to modify theme templates, layouts, or partials beyond what config allows
The upstream theme is stable and you don’t need to pull updates
You want simpler CI/CD without recursive submodule clones

When Not to Use#

The theme receives frequent updates you want to track
You only need CSS overrides (use assets/ or static/ instead)

Git Push Authentication, Ilmarë Website, Self-Hosted CMS Options & Landscape