HOWTO · Git

How to Remove a Submodule in Git

This tutorial is about removing submodules in Git

On this page

Removing a submodule in Git takes two commands from the superproject’s root: git submodule deinit <path> to unregister it locally, then git rm <path> to delete the tracked entry and stage the change. A submodule is a separate Git repository that the superproject tracks through a gitlink in the index and an entry in .gitmodules, so removal touches the working tree, the index, and that configuration file together.

Projects often vendor an external library or shared component as a submodule while keeping its history separate from the main repository. When that dependency is no longer needed, the steps below remove it cleanly, using a submodule named good-ext-lib as the example.

Remove a Git submodule

Run the following commands from the root of the superproject, replacing path/to/good-ext-lib with the submodule’s path as it appears in .gitmodules:

  • git submodule deinit path/to/good-ext-lib
  • git rm path/to/good-ext-lib

That is the whole removal. Neither command needs a force option in the normal case: add -f to git submodule deinit only to discard uncommitted work inside the submodule, and to git rm only to remove a submodule that still has local modifications or staged content. Both uses are destructive and throw away work, so reach for them only when that is the intent.

Run this self-contained example to try the full sequence in a scratch repository:

set -e
demo=$(mktemp -d)

git init -q -b main "$demo/lib"
git -C "$demo/lib" config user.email demo@example.com
git -C "$demo/lib" config user.name Demo
echo "demo library" > "$demo/lib/README.md"
git -C "$demo/lib" add README.md
git -C "$demo/lib" commit -qm "Initial library commit"

git init -q -b main "$demo/super"
git -C "$demo/super" config user.email demo@example.com
git -C "$demo/super" config user.name Demo
git -C "$demo/super" -c protocol.file.allow=always submodule add -q "$demo/lib" good-ext-lib
git -C "$demo/super" commit -qm "Add good-ext-lib submodule"

git -C "$demo/super" submodule deinit good-ext-lib
git -C "$demo/super" rm -q good-ext-lib
git -C "$demo/super" status --short

The script builds a small library repository, embeds it as a submodule in a scratch superproject, and then deinitializes and removes it; the final status command lists the staged result. Adapt the last three git -C "$demo/super" lines to a real repository by running the same subcommands — submodule deinit, rm, and status — without -C, at the project root.

Understand what each command changes

git submodule deinit path/to/good-ext-lib affects only the local clone. It removes the submodule.good-ext-lib registration from .git/config and clears the submodule’s working tree, but it stages nothing and leaves .gitmodules untouched.

git rm path/to/good-ext-lib performs the tracked removal. It deletes the gitlink — the index entry that records which commit the submodule is pinned to — removes the submodule’s section from .gitmodules, deletes the working-tree directory, and stages all of those changes for the next commit.

The actual cloned repository behind a submodule lives under .git/modules, here .git/modules/path/to/good-ext-lib. Neither command above deletes it, which is why re-adding a submodule under the same name can reuse the cached clone. Remove that directory by hand only to reclaim the space or force a completely fresh clone, and only after the removal is committed, because doing so permanently discards the local copy.

Verify and commit the removal

Before committing, review what was staged: git status lists the deleted gitlink and the .gitmodules change, and git diff --cached shows the same edits as a patch. Then record the removal like any other change with git commit -m "Remove submodule good-ext-lib".

The commit is the only step that other clones see — it is the superproject’s record that the submodule is gone. Deleting leftover metadata under .git/modules is purely local housekeeping and is never part of the commit; clones that pull this change stop tracking the submodule automatically.

Further reading

  1. git-submodule
  2. Git Submodule Tutorial