Table of contents

• What is a Git submodule?
• Steps to remove a Git submodule
• Removing all submodules
• Frequently asked questions

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.

Frequently asked questions

What happens to my local changes when I remove a submodule?

When you remove a submodule, any local changes you've made within the submodule directory will be lost. The removal process deletes the entire submodule directory and its contents. If you have important changes in the submodule that you want to keep, make sure to commit them to the submodule's repository before removing it, or copy them to another location.

Can I remove a submodule if it has uncommitted changes?

Yes, you can remove a submodule even if it has uncommitted changes, but those changes will be permanently lost. The removal process will delete the entire submodule directory regardless of its state. If you need to preserve any uncommitted changes, consider committing them to the submodule first, or copying the files to a different location before removal.

What if I accidentally remove the wrong submodule?

If you accidentally remove the wrong submodule, you can restore it by re-adding it using git submodule add <repository-url> <path>. However, any local changes that were in the submodule will be lost. You'll need to re-clone the submodule and reapply any local modifications you had made.

Do I need to remove the submodule from all branches?

No, you only need to remove the submodule from the branch where you're currently working. However, if you want to completely eliminate the submodule from your entire repository history, you may need to remove it from all branches or consider using git filter-branch or git filter-repo to clean up the entire history.

Will removing a submodule affect other team members?

Yes, removing a submodule will affect other team members. When they pull your changes, they'll need to run git submodule update --init --recursive to sync their local repositories. If they have local changes in the submodule, they should commit or stash them before pulling your changes.

Can I remove a submodule and replace it with regular files?

Yes, you can remove a submodule and replace it with regular files. After removing the submodule, you can copy the files from the submodule's repository into your main repository and add them as regular tracked files. This approach eliminates the submodule dependency but means you'll need to manually manage updates to those files.

What's the difference between git rm --cached and git rm for submodules?

When removing a submodule, git rm --cached removes the submodule from Git's index and staging area but leaves the actual files in your working directory. This is necessary because submodules are tracked as special entries in Git, not as regular files. The --cached flag ensures that Git removes the submodule reference without trying to delete the files (which you'll do manually with rm -rf).

How do I check if a submodule was completely removed?

After removing a submodule, you can verify it's completely gone by checking:

1. The .gitmodules file no longer contains the submodule entry
2. The .git/config file no longer has the submodule section
3. The submodule directory no longer exists in your project
4. Running git submodule status shows no reference to the removed submodule
5. The .git/modules/ directory no longer contains the submodule's metadata