How to effectively delete a git submodule

ยท ยท 441 words ยท 3 minute read

I need to remove a git submodule from my Hugo website. I installed a theme called kmt for my web blog, but I want to remove it now. It is nice to mention that the kmt hugo theme is open source and developed by me.

To remove a submodule you need to:

delete the relevant section from the .gitmodules file ๐Ÿ”—

[submodule "themes/ananke"]
 path = themes/ananke
 url =
-[submodule "themes/kmt"]
- path = themes/kmt
- url =

hint: lines starting with - is removed.

stage the .gitmodules changes ๐Ÿ”—

Use this command git add .gitmodules to stage the changes in local git.

delete the relevant section from .git/config ๐Ÿ”—

 repositoryformatversion = 0
 filemode = true
 bare = false
 logallrefupdates = true
 ignorecase = true
 precomposeunicode = true
[remote "origin"]
 url =
 fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
 remote = origin
 merge = refs/heads/main
[submodule "themes/ananke"]
 url =
 active = true
[remote "codeberg"]
 url =
 fetch = +refs/heads/*:refs/remotes/codeberg/*
[remote "gitlab"]
 url =
 fetch = +refs/heads/*:refs/remotes/gitlab/*
-[submodule "themes/kmt"]
- url =
- active = true

note: the minus - before lines hinting that these lines is deleted.

remove cached submodule ๐Ÿ”—

Just run git rm --cached path_to_submodule, for my case it is git rm --cached themes/kmt. Make sure no trailing slash in the path of submodule; I mean use themes/kmt not themes/kmt/.

remove all files in the submodule in the git ๐Ÿ”—

Run rm -rf .git/modules/path_to_submodule. For my case, it is rm -rf .git/modules/themes/kmt. Make sure no trailing slash in the path of submodule; I mean use .git/modules/themes/kmt not .git/modules/themes/kmt/.

commit the changes ๐Ÿ”—

Commit by git commit -m "build: removed submodule 'themes/kmt'". Rewrite the commit message that is relevant to your case.

Delete the local untracked directory/folder ๐Ÿ”—

Delete the now untracked submodule files using this command rm -rf path_to_submodule which is rm -rf themes/kmt in my case.

Update : modern git have a simpler way ๐Ÿ”—

Here are the steps of the modern git, which also works fine like the conventional one we used above.

  • remove the submodule entry from .git/config
git submodule deinit -f path/to/submodule
# in my case
git submodule deinit -f themes/kmt
  • remove the submodule directory from the superproject’s .git/modules directory
rm -rf .git/modules/path/to/submodule
# in my case
rm -rf .git/modules/themes/kmt
  • remove the entry in .gitmodules and remove the submodule directory located at path/to/submodule
git rm -f path/to/submodule
# in my case
git rm -f themes/kmt

I hope this post helps you with your programming journey. If you want to get notified about new posts, follow me on YouTube , Twitter (x) , LinkedIn , Facebook , Telegram and GitHub .