How to remove submodules in Git
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
Removing Git submodules requires careful steps to clean up the submodule registration, working directory, and Git configuration files.
As the creator of CoreUI with over 25 years of version control experience since 2000, I’ve managed submodules in complex projects and understand the importance of proper removal.
The recommended approach uses git submodule deinit to unregister the submodule, followed by removing the submodule directory and cleaning up .gitmodules.
This ensures complete removal without leaving orphaned references.
Use git submodule deinit followed by git rm to remove a submodule.
git submodule deinit -f path/to/submodule
git rm -f path/to/submodule
git commit -m "Remove submodule path/to/submodule"
The git submodule deinit command unregisters the submodule from .git/config and removes its working directory contents. The -f flag forces removal even if the submodule has local changes. The git rm command removes the submodule directory and updates .gitmodules. The commit finalizes the removal.
Complete Submodule Removal Process
Follow these steps to completely remove a submodule from the repository.
# Step 1: Deinitialize the submodule
git submodule deinit -f path/to/submodule
# Step 2: Remove the submodule directory
git rm -f path/to/submodule
# Step 3: Remove the submodule from .git/modules
rm -rf .git/modules/path/to/submodule
# Step 4: Commit the changes
git commit -m "Remove submodule: path/to/submodule"
The first command unregisters the submodule configuration. The second removes the submodule directory from the working tree and staging area. The third removes cached submodule data from .git/modules. The final commit records these changes. All four steps ensure complete cleanup.
Removing Multiple Submodules
Remove several submodules in a single operation.
# Remove first submodule
git submodule deinit -f libs/library1
git rm -f libs/library1
# Remove second submodule
git submodule deinit -f libs/library2
git rm -f libs/library2
# Remove third submodule
git submodule deinit -f libs/library3
git rm -f libs/library3
# Commit all removals
git commit -m "Remove submodules: library1, library2, library3"
Each submodule requires its own deinit and rm commands. After removing all submodules, a single commit can record all changes. This approach keeps the commit history clean and groups related removals together.
Removing All Submodules
Remove every submodule from the repository at once.
# List all submodules
git submodule status
# Remove each submodule
git submodule foreach 'git submodule deinit -f $path'
git rm -f $(git config --file .gitmodules --get-regexp path | awk '{ print $2 }')
# Clean up .git/modules
rm -rf .git/modules/*
# Commit the changes
git commit -m "Remove all submodules"
The git submodule foreach command runs deinit for each submodule. The git config --get-regexp extracts all submodule paths from .gitmodules. The awk command formats the paths for removal. The rm -rf .git/modules/* clears cached submodule data. This approach handles any number of submodules automatically.
Handling Submodule Removal Errors
Resolve common errors during submodule removal.
# If deinit fails due to local changes
git submodule deinit -f path/to/submodule
# If .git/modules is not accessible
sudo rm -rf .git/modules/path/to/submodule
# If .gitmodules has conflicts
git checkout --theirs .gitmodules
git add .gitmodules
# Verify clean state
git status
The -f flag forces deinit even with uncommitted changes. The sudo command handles permission issues in .git/modules. Checking out .gitmodules from the remote resolves merge conflicts. The git status command confirms successful removal.
Verifying Submodule Removal
Confirm the submodule has been completely removed.
# Check submodule status
git submodule status
# Verify .gitmodules content
cat .gitmodules
# Check .git/config
git config --list | grep submodule
# Verify directory is gone
ls -la path/to/submodule
The git submodule status should not list the removed submodule. The .gitmodules file should not contain references to it. The git config command should show no submodule entries. The directory should not exist in the working tree. These checks ensure complete removal.
Best Practice Note
This is the same submodule removal process we follow in CoreUI projects when restructuring repositories or replacing submodules with npm packages. Always commit submodule removals separately from other changes to keep the history clear. Before removing submodules, ensure you have backups or can access the submodule content elsewhere if needed. For teams transitioning away from submodules, consider documenting the removal process and alternative approaches (like npm packages or monorepos) to prevent future submodule additions. If you need to manage multiple repositories, consider using workspace features in package managers instead of Git submodules for easier dependency management.
