How to remove a Git submodule from your project

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.

What is a Git submodule?

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.

Steps to remove a Git submodule

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

1. Delete the submodule entry from .gitmodules

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.

vim .gitmodules

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

[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.

2. Remove the submodule entry from .git/config

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

vim .git/config

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

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

3. Remove the submodule directory and its contents

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

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.

4. Commit the changes

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

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

5. Push the changes to your remote repository

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

git push origin main

Removing all submodules

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.