Git submodules are a powerful feature that allows you to include and manage repositories within another repository. However, there might be times when you need to remove a submodule. Whether it’s because the submodule is no longer needed, or you want to simplify your repository structure, this guide will walk you through the steps to safely remove a submodule from your Git repository.

Steps to Remove a Submodule

Removing a submodule involves several steps, including updating the `.gitmodules` and `.git/config` files and cleaning up the submodule directory. Follow these steps to ensure a clean and complete removal of a submodule.

Step 1. Deinit the Submodule

First, deinitialize the submodule to remove its configuration from the Git index.

git submodule deinit -f --path/to/submodule

Replace `path/to/submodule` with the actual path to your submodule. This command removes the submodule’s entry from `.git/config`.

Step 2. Remove the Submodule Directory

After deinitializing the submodule, you need to remove the submodule directory from the repository

rm -rf path/to/submodule

This command deletes the submodule directory from your working directory.

Step 3. Remove the Submodule Entry from .gitmodules

Open the `.gitmodules` file in a text editor and remove the entry for the submodule.

[submodule "path/to/submodule"]    
path = path/to/submodule    
url = https://github.com/username/repository.git

Remove the entire block related to the submodule you want to delete.

Step 4. Remove the Submodule Entry from .git/config

Next, open the `.git/config` file and remove the configuration block for the submodule.

[submodule "path/to/submodule"]    
url = https://github.com/username/repository.git

Remove the corresponding block to ensure no references remain.

Step 5. Commit the Changes

Now that you’ve removed the submodule’s configuration and directory, commit the changes to your repository.

git add .gitmodules
git add -u
git commit -m "Remove submodule path/to/submodule"

Step 6. Clean Up Unused Submodule References

Finally, clean up any unused references to the submodule by running the following command:

git rm -r --cached path/to/submodule

This command ensures that all references to the submodule are removed from the Git index.

Example

Here’s an example of removing a submodule located at `libs/mysubmodule`:

Step 1. Deinit the submodule:

    git submodule deinit -f --libs/mysubmodule

Step 2. Remove the submodule directory:

    rm -rf libs/mysubmodule

Step 3. Remove the submodule entry from `.gitmodules`:

Edit the `.gitmodules` file and remove the following block:

[submodule "libs/mysubmodule"]        
path = libs/mysubmodule        
url = https://github.com/username/mysubmodule.git

Step 4. Remove the submodule entry from `.git/config`:

Edit the `.git/config` file and remove the corresponding block:

[submodule "libs/mysubmodule"]        
url = https://github.com/username/mysubmodule.git

Step 5. Commit the changes:

 git add .gitmodules    
git add -u    
git commit -m "Remove submodule libs/mysubmodule"

Step 6. Clean up unused submodule references:

git rm -r --cached libs/mysubmodule

Conclusion

Removing a submodule in Git requires careful handling of configuration files and the repository’s index. By following the steps outlined in this guide, you can ensure that the submodule is completely and cleanly removed from your repository. This process helps maintain the integrity and cleanliness of your project, avoiding potential issues with leftover references.