0Pricing
Git Advanced: Monorepo, Submodules & Workflows · Lesson

Removing and Deinitializing Submodules

Learn the correct, complete procedure for removing a Git submodule from a repository, including deinitialization, cleanup of .gitmodules, and avoiding leftover state.

Removing and Deinitializing Submodules is a free Git Advanced: Monorepo, Submodules & Workflows lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Git Advanced: Monorepo, Submodules & Workflows learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

When You Need to Remove a Submodule

Submodules are added to pull in external code, but requirements change. You may need to remove one when the dependency is replaced, vendored directly, or simply no longer needed.

Removal is more involved than deleting a folder: a submodule lives in several places at once, and missing one leaves your repo in a broken state.

Where a Submodule Lives

A submodule has three footprints:

  • .gitmodules — the declarative config
  • .git/config — your local active config
  • .git/modules/<path> — the cached submodule git data

Plus the working tree folder itself. Clean removal touches all of these.

Step 1: Deinitialize

Start with git submodule deinit. This unregisters the submodule and removes its entry from .git/config, leaving the rest intact for now.

git submodule deinit -f path/to/submodule

Step 2: Remove from the Index

Use git rm to remove the submodule from tracking and from the working tree. This also updates .gitmodules automatically in modern Git.

git rm -f path/to/submodule

Step 3: Clean the Cached Git Data

The submodule's git data lingers under .git/modules. Remove it so a future submodule with the same path does not collide.

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

Verify .gitmodules Is Clean

Open .gitmodules and confirm the [submodule "..."] block is gone. If git rm left an empty file or a stale entry, fix it by hand and stage the change.

git diff --cached .gitmodules

Step 4: Commit the Removal

The removal must be committed so collaborators get the change. The commit captures the deleted folder, the updated .gitmodules, and the dropped index entry.

git commit -m 'Remove path/to/submodule'

The Manual Fallback

On older Git versions git rm may not edit .gitmodules for you. The manual path:

git config -f .gitmodules --remove-section submodule.path/to/submodule
git add .gitmodules
git rm --cached path/to/submodule
rm -rf path/to/submodule

What Collaborators See

When teammates pull the removal commit, the folder disappears from tracking. But their local .git/modules cache and .git/config entry may persist. Tell them to run git submodule sync and clean up if needed.

Common Mistakes

  • Deleting only the folder with rm -rf — leaves a broken index entry
  • Forgetting .git/modules cleanup — blocks re-adding the same path
  • Not committing the .gitmodules change — others still see the submodule

A Reusable Checklist

Whenever you remove a submodule, run through: deinit, rm, clean modules cache, verify .gitmodules, commit. Following the same order every time prevents the half-removed states that confuse a whole team.

Quick Check

Test your understanding of removing submodules.

Recap

You learned the complete removal procedure: deinit to unregister, git rm to drop tracking, clean .git/modules to clear the cache, verify .gitmodules, then commit. Following this checklist every time keeps both your repo and your collaborators' clones healthy.

Frequently asked questions

Is the “Removing and Deinitializing Submodules” lesson free?

Yes — the full text of “Removing and Deinitializing Submodules” is free to read here on the web, and the Git Advanced: Monorepo, Submodules & Workflows course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Git Advanced: Monorepo, Submodules & Workflows course, upgrade to CoddyKit PRO.

What will I learn in “Removing and Deinitializing Submodules”?

Learn the correct, complete procedure for removing a Git submodule from a repository, including deinitialization, cleanup of .gitmodules, and avoiding leftover state. You practise Git Advanced: Monorepo, Submodules & Workflows with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Git Advanced: Monorepo, Submodules & Workflows?

No prior experience is required. Git Advanced: Monorepo, Submodules & Workflows on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Removing and Deinitializing Submodules” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Git Advanced: Monorepo, Submodules & Workflows lesson?

Yes. Every Git Advanced: Monorepo, Submodules & Workflows lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Introduction to Git Submodules
  2. Adding and Cloning Submodules
  3. Updating and Synchronizing Submodules
  4. Removing and Deinitializing Submodules
← Back to Git Advanced: Monorepo, Submodules & Workflows