Module 7 Lesson 5: Removing submodules

Adding a submodule is easy; removing one is surprisingly manual. Unlike many other Git operations, there isn't a single command like git submodule remove. You have to carefully "unregister" the dependency from multiple places.

In this lesson, we learn the step-by-step procedure to cleanly remove a submodule from your project.

---

1. The 4-Step Removal Process

If you wanted to remove a submodule located at libs/ui, follow these steps:

Step 1: Remove from the Staging Area

Tell Git to stop tracking the folder.

git rm -f libs/ui

(The -f flag is often needed because the submodule contains its own .git directory).

Step 2: Delete the entry in .gitmodules

Open the .gitmodules file in a text editor and delete the section corresponding to that submodule. If it was your only submodule, you can delete the file entirely.

Step 3: Delete from Internal Config

Git also keeps a record of the submodule inside your hidden .git/config file.

# In modern Git
git config --remove-section submodule.libs/ui

Step 4: Cleanup the Internals

Git stores a cached copy of the submodule's history in its internal objects. To fully wipe it:

rm -rf .git/modules/libs/ui

---

2. Commit the Removal

Just like any other change, the removal isn't "official" until you commit it.

git add .gitmodules
git commit -m "Remove UI library submodule"

---

3. Why is it so manual?

Git is designed to be conservative. It doesn't want to accidentally delete history. Because a submodule is its own repository, Git makes the removal process deliberate so you don't lose the record of which version of the library was used in your project's past.

graph TD
    Project["Parent Project"]
    SubDir["Submodule Folder"]
    MetaConfig[".git/config"]
    ModuleMeta[".gitmodules"]
    Internal[".git/modules/"]
    
    Project -- "1. git rm" --> SubDir
    Project -- "2. Edit" --> ModuleMeta
    Project -- "3. git config" --> MetaConfig
    Project -- "4. rm -rf" --> Internal

---

Module 7 Comprehensive Practice Exercises

Let's practice the complete lifecycle of project architecture:

1. Addition: Add an external repo as a submodule external/test-lib.
2. Commit: Commit the addition in your parent repository.
3. Investigation: Look inside .gitmodules and .git/config to see the registration.
4. The Update: Change the version of the submodule (checkout a specific tag or old commit ID inside the submodule).
5. The Synchronization: Commit the "new pointer" version in the parent repo.
6. The Removal: Follow the 4-step process above to fully remove external/test-lib.
7. The Proof: Run git status and ls -a. Ensure the folders are gone and the .gitmodules file is clean.

Checkpoint: If you successfully removed the submodule without leaving "ghost" folders behind, you have mastered one of the most technical tasks in Git!

---

Summary

In this lesson, we established:

• Removing a submodule requires cleaning up .gitmodules, .git/config, and git rm.
• You must manually delete the internal cache in .git/modules/.
• Always commit your clean-up to inform the rest of your team.

Module Complete! You are now capable of architecting complex, multi-repo projects.

Next Module: We’ll look at the "Big Picture." Welcome to Module 8: Git Workflows, where we’ll learn how to organize teams using Git Flow, GitHub Flow, and Trunk-Based Development.