How Do I Remove a Submodule?

Question

How do I remove a Git submodule?

By the way, is there a reason I can't simply do git submodule rm whatever ?

Accepted Answer

In modern git (I'm writing this in 2022, with an updated git installation), this has become quite a bit simpler:

Run git rm <path-to-submodule>, and commit.

This removes the filetree at <path-to-submodule>, and the submodule's entry in the .gitmodules file. I.e. all traces of the submodule in your repository proper are removed.

As the docs note however, the .git dir of the submodule is kept around (in the modules/ directory of the main project's .git dir), "to make it possible to checkout past commits without requiring fetching from another repository".
If you nonetheless want to remove this info, manually delete the submodule's directory in .git/modules/, and remove the submodule's entry in the file .git/config. These steps can be automated using the commands

rm -rf .git/modules/<path-to-submodule>, and
git config --remove-section submodule.<path-to-submodule>.

Older community wiki instructions:

Via the page Git Submodule Tutorial:

To remove a submodule you need to:

Delete the relevant section from the .gitmodules file.
Stage the .gitmodules changes:
git add .gitmodules
Delete the relevant section from .git/config.
Remove the submodule files from the working tree and index:
git rm --cached path_to_submodule (no trailing slash).
Remove the submodule's .git directory:
rm -rf .git/modules/path_to_submodule
Commit the changes:
git commit -m "Removed submodule <name>"
Delete the now untracked submodule files:
rm -rf path_to_submodule

See also: alternative steps below.

Accepted Answer

Since git1.8.3 (April 22d, 2013):

There was no Porcelain way to say "I no longer am interested in this submodule", once you express your interest in a submodule with "git submodule init".
"git submodule deinit" is the way to do so.

The deletion process also uses git rm (since git1.8.5 October 2013).

Must Read

Summary

The 3-steps removal process would then be:

0. mv a/submodule a/submodule_tmp

1. git submodule deinit -f -- a/submodule    
2. rm -rf .git/modules/a/submodule
3. git rm -f a/submodule
# Note: a/submodule (no trailing slash)

# or, if you want to leave it in your working tree and have done step 0
3.   git rm --cached a/submodule
3bis mv a/submodule_tmp a/submodule

How Do I Remove a Submodule?

36 Answers

Must Read

Summary

James H. Sterling