Submodule / git

snoop@Snoop hugoMyWebsite % git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
  (commit or discard the untracked or modified content in submodules)
	modified:   themes/atlantic (modified content)

So I was chipping on a theme and was like “oh the docs say to put themes in submodules” so I put my own theme as a separate repo and brought it in as a submodule, but clearly I did something cause not git is yelling at me.

Probably something simple, but I’m just not seeing it. Any tips?

It looks like you have modified the theme.

That means you need to change to the themes/atlantic directory, commit you changes and push theme.
Then you need to git add themes/atlantic and add a commit (probably with a message indicating you have updated the theme) to you main repo.

Basically, because themes/atlantic is no longer part of the main repo you have to update it separately, and because it is a submodule you have to commit the reference to commit you want to be using, in your main repo.

Maybe this will help: Git - Submodules.

Finally, which (outdated) docs suggested a submodule? In general the preferred ‘modern’ Hugo approach is to use Hugo Modules: Hugo Modules | Hugo


I have started using Modules, but I personally think that the git submodule approach shouldn’t be called “outdated”. That approach is robust, has been working great, and doesn’t need a user to install go on their system.

@willduncanphoto I’d encourage you to learn git and submodules as that is an immensely useful git skill in general; not just for maintaining your Hugo site and theme in separate repos. But if you see that learning git is not important for you, install go and check out the Hugo Modules link shared above.

1 Like

Yeah, I am interested in submodules and learning git more. I just can’t seem to wrap my head around how to work with a template as a submodule and make changes inside another git repo. I broke it on the first day.

That’s what I thought too! And I’m not sure where I’m not connecting the dots here.

snoop@Snoop hugoAtlantic % git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

I’m a little confused. Is your theme in themes/atlantic or themes/hugoAtlantic ? Or do you have both, and the you have a modified ‘atlantic’ tree but are (above) looking at the unmodified ‘hugoAtlantic’ tree?

Or, did you ‘name’ the submodule ‘atlantic’ but have it in subdir ‘hugoAtlantic’?

I’m probably making a mess of all of it while trying to fix it. So I doubt that’s helped.

I took the /atlantic template out of my project, moved it over to another repo named hugoAtlantic and pulled it back in to my hugo project as a submodule. That read as the most logical way to manage it. But I think I missed some documentation on how to work with submodules and made up my own assumptions.

I’m just gonna take the easy road out and move my theme back inside my hugo repo. I can’t figure it out and it’s not worth the effort atm.

If you’re not going to use the theme elsewhere, take an even easier route and eliminate the themes directory — use the project level directories (archetypes, assets, data, i18n, layouts, static) instead. For a lot of projects I find this easier, less cluttered.


@willduncanphoto I can appreciate that, and agree with Joe about ditching the themes directory altogether if you are not planning on reusing the theme. I think @kaushalmodi is partly right in that learning git submodules is a useful skill and I’ll add (though you can already see) it can be a bit tricky.

I think Hugo modules are a) easier to use b) AIUI what is being supported and promoted by the Hugo devs going forward and for some time now (which is what I meant by outdated; not that outside Hugo git submodules are outdated, but that for the purposes of Hugo if you use git submodules you are more or less on your own) c) allow the use of a modularized/componentized approach to Hugo themes and/or sites without themes which I would not recommend trying with git submodules.

I can get on board with that! Less is more, almost always.

I never even thought twice to use hugo that way. First tutorial said to use a theme, and I never looked back and thought about it. Thought the defaults were more for emergency fallback variants with some inheritance that I didn’t know about. I make poor choices based on assumptions it seems.

I’d love to collect a best practices guide one day.

1 Like

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.