tldr: If you make any changes to the file path of a git submodule, you need to also update all of your config files accordingly.

Background

I use the Papermod Hugo theme for my personal website. One of the ways to use Hugo themes is to install them as a submodule inside your project’s ./themes directory. I wanted to update the module today as there have been a number of changes since I set it up.

Normally, with a submodule, you would just navigate to the directory containing the submodule and run your standard git pull commands to incorporate any changes to the remote. Unfortunately for me, when I got to my Papermod directory and ran git status to see where the repo was, I got a fatal: not a git repository error.

Thankfully, git gives you a bit of a breadcrumb trail to follow in it’s error code: a path. I checked the path and it wasn’t pointing to the right .git/module. After some minutes of head scratching, I realized there was an extra themes/ in the error that git threw. Then I remembered that I had moved my Papermod directory after realizing there was a redundant themes directory in its original location.

It turns out I had just copy pasted the Papermod instructions for adding the theme as a submodule without thinking about what directory I was in:

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

Note that themes/ in the final argument of the command. This assumes you are in your site’s main directory. I was already in the themes directory, so instead of installing the module at ./themes/Papermod, I installed it at ./themes/themes/Papermod.

Fix

To fix this, I had to update all of the file references in all of the git config files that allow the main directory to talk to the submodule. That means updating four different config files1 with the changes that were made:

1. .gitmodules

You will find an entry that looks like this:

[submodule "themes/themes/PaperMod"]
	path = themes/themes/PaperMod
	url = https://github.com/adityatelange/hugo-PaperMod.git

Change the path and submodule lines to reflect your changes. In my case, I just had to delete the redundant themes/. Note that the submodule path (the part in quotes) is relative to your repo’s root directory.

2. .git/config

The entry looks quite similar to .gitmodules:

[submodule "themes/themes/PaperMod"]
	url = https://github.com/adityatelange/hugo-PaperMod.git
	active = true

Just change the submodule line to match the .gitmodules file.

3. .git/modules/<SUBMODULE_PATH>/config

SUBMODULE_PATH should correspond to the path entry in .gitmodules. For me, this is .git/modules/themes/Papermod/config. This file will have a [core]` section that looks like this:

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
	ignorecase = true
	precomposeunicode = true
	worktree = ../../../../../themes/themes/PaperMod

The last line (worktree) is the one we are interested in. This needs to point to your submodule’s root directory2.

4. themes/<THEME_NAME>/.git

Here you will find a line like this:

gitdir: ../../../.git/modules/themes/themes/PaperMod

Change this to point to the module directory in the root repo’s .git folder. Make sure your ../s take you to the root directory. Since I brought my submodule up a level, I had to remove one ../.

And that’s it! Now when you run git status, you will hopefully see something like the following:

On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Happy versioning!

  1. I found these files with grep (the -r and I will search and ignore directories, respectively) ↩︎

  2. Note that if you are changing the hierarchy and not just the name, you will will have to change the relative directory refferences (i.e. the number of ../ you have) and not just the names. Since I moved my submodule up a directory, I had to remove a set of ../ as well as a themes/. ↩︎