How to effectively delete a git submodule

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 = https://github.com/theNewDynamic/gohugo-theme-ananke.git
-[submodule "themes/kmt"]
- path = themes/kmt
- url = https://github.com/abanoubha/gohugo-theme-kmt.git

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 🔗

[core]
 repositoryformatversion = 0
 filemode = true
 bare = false
 logallrefupdates = true
 ignorecase = true
 precomposeunicode = true
[remote "origin"]
 url = https://github.com/abanoubha/abanoubhanna-web.git
 fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
 remote = origin
 merge = refs/heads/main
[submodule "themes/ananke"]
 url = https://github.com/theNewDynamic/gohugo-theme-ananke.git
 active = true
[remote "codeberg"]
 url = https://codeberg.org/abanoubha/abanoubhanna-web.git
 fetch = +refs/heads/*:refs/remotes/codeberg/*
[remote "gitlab"]
 url = https://gitlab.com/abanoubha/abanoubhanna-web.git
 fetch = +refs/heads/*:refs/remotes/gitlab/*
-[submodule "themes/kmt"]
- url = https://github.com/abanoubha/gohugo-theme-kmt.git
- 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 , and GitHub .