How to remove a Git submodule from your project

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Git submodules allow you to keep a Git repository as a subdirectory of another Git repository. This is an effective way to manage projects that depend on external libraries or other projects. However, if a submodule is no longer needed, or if it was added incorrectly, you may need to remove it. This guide details how to properly remove a Git submodule from your repository.

A Git submodule is a mechanism in Git that allows you to include a repository within another repository as a subdirectory. It enables you to keep another repository's files and commits as part of your repository while maintaining their separate version control. Submodules are particularly useful for including libraries or other projects where you want to maintain a specific version of the external code without merging it into your main project.

Essentially, a submodule links a specific commit in the external repository to your main repository. This link allows you to control exactly which version of the external project is used, preventing automatic updates that might break or interfere with your main project. You can update the submodule when necessary to a newer commit, providing a controlled method to manage external dependencies.

Removing a submodule involves several steps to ensure that the main repository and its working directory are cleanly updated without leftover components.

First, you need to manually edit the .gitmodules file and remove the entry for the submodule. This file is located in the root directory of your main repository and contains metadata about your submodules.

Terminal
vim .gitmodules

In the .gitmodules file, delete the section corresponding to the submodule you want to remove, which looks like this:

Terminal
[submodule "path/to/submodule"]
path = path/to/submodule
url = https://github.com/example/repo.git

Once you've deleted the relevant section, save and exit the file.

Next, open the Git configuration file for your repository and remove the submodule's entry:

Terminal
vim .git/config

Find the section related to your submodule and delete it before saving the file:

Terminal
[submodule "path/to/submodule"]
url = https://github.com/example/repo.git

Once the configurations are updated, you need to remove the actual submodule files from your project:

Terminal
git rm --cached path/to/submodule
rm -rf .git/modules/path/to/submodule
rm -rf path/to/submodule

The git rm --cached command removes the submodule from the index and staging area but leaves the local files intact. The subsequent rm -rf commands delete the submodule's directory and clean up the Git module's metadata.

After removing the submodule, commit the changes to your repository to finalize the removal:

Terminal
git add .
git commit -m "Removed submodule [submodule name]"

Finally, push your changes to ensure that the remote repository is updated:

Terminal
git push origin main

If your project has multiple submodules and you need to remove all of them, you should repeat the steps above for each submodule. There's no built-in Git command to remove all submodules at once, but you can script the process by parsing the .gitmodules file.

For further reading on Git submodules see the official Git documentation.

Git gud
"It's the first Git workflow I've used that actually feels good."
–@robboclancy
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2