Avoiding Git Problems When Installing a Theme to Hugo

tl;dr

If you didn't install your hugo theme as a submodule then don't forget to delete the .git folder from the theme's folder.

# assuming you start from repo root
cd themes

# install the "hyde" theme
git clone https://github.com/spf13/hyde.git
rm -rf hyde/.git

# now go back to repo root and stage the new theme folder
cd ..
git add themes/hyde

If you forget to delete the theme's .git folder then you might see the error fatal: in unpopulated submodule. To fix this, remove the theme folder from the git cache:

# assuming you start from repo root
# remove the theme folder from the git cache (but don't remove from file system)
git rm --cached themes/hyde

# now you can add the theme folder
git add themes/hyde

long version

If you are new to hugo you might run into some git troubles after installing a theme.

Hugo uses git to install themes and if you are like me you might not have read (or glossed over) this little nugget from the theme documentation:

Before you use a theme, remove the .git folder in that theme’s root folder. Otherwise, this will cause problem if you deploy using Git.

If you install a theme via git clone but forget to delete the .git folder in that theme's folder then your newly-installed theme will not get picked up when you attempt to commit the changes to your site.

Here are the commands I use to install themes (same as tl;dr above):

# assuming you start from repo root
cd themes

# using hyde theme for this example
git clone https://github.com/spf13/hyde.git
rm -rf hyde/.git

# now go back to repo root and stage the new theme folder
cd ..
git add themes/hyde

What if I forget to remove the .git folder?

If you already committed before deleting the theme's .git folder then you might see the error fatal: in unpopulated submodule whenever you try to git add that theme's folder.

To fix this remove the .git folder from your theme's folder as described above and then remove the theme folder from the git cache (same as tl;dr above):

# assuming you start from repo root
# remove the theme folder from the git cache (but don't remove from file system)
git rm --cached themes/hyde

# now you can add the theme folder
git add themes/hyde

Or use submodules

Of course, you can always install themes as submodules and not have to deal with deleting any .git folder... but then you have to deal with submodules. Personally, I find submodules annoying (I always forget to sync them after cloning a repo), so I'd rather just use git clone and delete the .git folder instead of using git submodule add. For the sake of completeness this is how to install the theme as a submodule:

# assuming you start from repo root
cd themes
git submodule add https://github.com/spf13/hyde.git