How do I remove a Git submodule?
How do I remove a Git submodule?

And by the way, is there a reason I can't simply do 

improve this question | comment
Aileen MacGyver Created at: 2013-11-13 17:07:29 UTC By Aileen MacGyver
If your goal is to Replace the submodule with a different submodule, read this ... - Gaetano Steuber
@jondavidjohn You can replace submodules now, see… - Daron Dibbert
Since git1.8.3 (April 22d, 2013), you have git submodule deinit, see my answer below. - Camille Kassulke
this script is doing exactly what you ask for - Ms. Jaquelin Lueilwitz
Soon git rm submodule will work as expected ;) I have edited my answer below. - Quentin Jerde
13 Answers
I recently find out a git project which include many useful git related command:

Install it and type:

git-delete-submodule submodule

Then things are done. The submodule directory will be removed from your repo and still exist in your filesystem. You can then commit the change like: git commit -am "Remove the submodule".
You can use an alias to automate the solutions provided by others:

  rms = "!f(){ git rm --cached \"$1\";rm -r \"$1\";git config -f .gitmodules --remove-section \"submodule.$1\";git config -f .git/config --remove-section \"submodule.$1\";git add .gitmodules; }; f"

Put that in your git config, and then you can do: git rms path/to/submodule
Simple steps

Remove config entries:git config -f .git/config --remove-section submodule.$submodulepathgit config -f .gitmodules --remove-section submodule.$submodulepath
Remove directory from index:git rm --cached $submodulepath
Delete unused files:rm -rf $submodulepathrm -rf .git/modules/$submodulepath
Please note: $submodulepath doesn't contain leading or trailing slashes.


When you do git submodule add, it only adds it to .gitmodules, but
once you did git submodule init, it added to .git/config.

So if you wish to remove the modules, but be able to restore it quickly,
then do just this:

git rm --cached $submodulepath
git config -f .git/config --remove-section submodule.$submodulepath

It is a good idea to do git rebase HEAD first and git commit
at the end, if you put this in a script.

Also have a look at an answer to Can I unpopulate a Git submodule?.
In addition to the recommendations, I also had to rm -Rf .git/modules/path/to/submodule to be able to add a new submodule with the same name (in my case I was replacing a fork with the original)
You must remove the entry in .gitmodules and .git/config, and remove the directory of the module from the history:

git rm --cached path/to/submodule

If you'll write on git's mailing list probably someone will do a shell script for you.
To summarize, this is what you should do:

Set path_to_submodule var (no trailing slash): 

Delete the relevant line from the .gitmodules file:

git config -f .gitmodules --remove-section submodule.$path_to_submodule
Delete the relevant section from .git/config

git config -f .git/config --remove-section submodule.$path_to_submodule
Unstage and remove $path_to_submodule only from the index (to prevent losing information) 

git rm --cached $path_to_submodule
Track changes made to .gitmodules

git add .gitmodules
Commit the superproject

git commit -m "Remove submodule submodule_name"
Delete the now untracked submodule files

rm -rf $path_to_submodule

rm -rf .git/modules/$path_to_submodule
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.
Run git rm --cached path_to_submodule (no trailing slash).
Run rm -rf .git/modules/path_to_submodule
Commit git commit -m "Removed submodule <name>"
Delete the now untracked submodule filesrm -rf path_to_submodule
If the submodule was accidentally added because you added, committed and pushed a folder that was already a Git repository (contained .git), you won’t have a .gitmodules file to edit, or anything in .git/config. In this case all you need is:

git rm --cached subfolder
git add subfolder
git commit -m "Enter message here"
git push

FWIW, I also removed the .git folder before doing the git add.
What I'm currently doing Dec 2012 (combines most of these answers): 

git config -f .git/config --remove-section "submodule.${oldPath}"
git config -f .gitmodules --remove-section "submodule.${oldPath}"
git rm --cached "${oldPath}"
rm -rf "${oldPath}"              ## remove src (optional)
rm -rf ".git/modules/${oldPath}" ## cleanup gitdir (optional housekeeping)
git add .gitmodules
git commit -m "Removed ${oldPath}"

this is a bash script you can download an install

helpful for updating or removing submodules
To remove a submodule added using:

git submodule add lib/blah


git submodule deinit lib/blah
git rm lib/blah
git config -f .gitmodules --remove-section submodule.lib/blah

(This solution is for git 1.8.4. In git 1.8.5 the final step will no longer be required)
I had to take John Douthat's steps one step further and cd into the submodule's directory, and then remove the Git repository: 

cd submodule
rm -fr .git

Then I could commit the files as a part of the parent Git repository without the old reference to a submodule.
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 "submodule init".
  "submodule deinit" is the way to do so.

There is work in progress to imporove git rm as well (potentially for git1.8.5 October 2013).
The all removal process would then be:

git submodule deinit asubmodule
git rm asubmodule

See commit 95c16418:

  Currently using "git rm" on a submodule removes the submodule's work tree from that of the superproject and the gitlink from the index.
  But the submodule's section in .gitmodules is left untouched, which is a leftover of the now removed submodule and might irritate users (as opposed to the setting in .git/config, this must stay as a reminder that the user showed interest in this submodule so it will be repopulated later when an older commit is checked out).
  Let "git rm" help the user by not only removing the submodule from the work tree but by also removing the "submodule.<submodule name>" section from the .gitmodules file and stage both.

In the meantime, the following section:

details the git submodule deinit command, 
and addresses the extra step you need to take to remove completely a submodule (from the index, and from the .gitmodules)
It stems from this patch:

  With "git submodule init" the user is able to tell git he cares about one or more submodules and wants to have it populated on the next call to "git submodule update".
  But currently there is no easy way he could tell git he does not care about a submodule anymore and wants to get rid of his local work tree (except he knows a lot about submodule internals and removes the "submodule.$name.url" setting from .git/config together with the work tree himself).
  Help those users by providing a 'deinit' command.
  This removes the whole submodule.<name> section from .git/config either for the given
  submodule(s) (or for all those which have been initialized if '.' is given).
  Fail if the current work tree contains modifications unless forced.
  Complain when for a submodule given on the command line the url setting can't be found in .git/config, but nonetheless don't fail. 

This takes care if the (de)initialization steps (.git/config and .git/modules/xxx)

It doesn't take care of the:

'add' step which records the url of a submodule in the .gitmodules file: you still need to remove it manually within that file.
the submodule special entry (as illustrated by this question): you still need to remove it from the index:git rm --cached path_to_submodule (no trailing slash)
That will remove that directory stored in the index with a special mode "160000", marking it as a submodule root directory.
If you forget that last step, and try to add what was a submodule as a regular directory, you would get error message like:

git add mysubmodule/file.txt 
Path 'mysubmodule/file.txt' is in submodule 'mysubmodule'

Adam Sharp very kindly provides us (in the comments) with a script to automate the steps mentioned above:

# Adam Sharp
# Aug 21, 2013
# Usage: Add it to your PATH and `git remove-submodule path/to/submodule`.
# Does the inverse of `git submodule add`:
#  1) `deinit` the submodule
#  2) Remove the submodule from the index and working directory
#  3) Clean up the .gitmodules file (won't be needed with 1.8.5!)

submodule_name=$(echo "$1" | sed 's/\/$//'); shift

exit_err() {
  [ $# -gt 0 ] && echo "fatal: $*" 1>&2
  exit 1

if git submodule status "$submodule_name" >/dev/null 2>&1; then
  git submodule deinit -f "$submodule_name"
  git rm -rf "$submodule_name"

  git config -f .gitmodules --remove-section "submodule.$submodule_name"
  if [ -z "$(cat .gitmodules)" ]; then
    git rm -f .gitmodules
    git add .gitmodules
  exit_err "Submodule '$submodule_name' not found"

Go in a directory in your PATH and type:

curl -o git-remove-submodule
chmod 755 git-remove-submodule

Note: curl works on Windows too, with GoW (Gnu on Windows), you just don't need the chmod step.
Your Answer