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#

1. Remove the submodule registration:

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

2. 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"

3. 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)

Related Pages#

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