Introduction

To "un-submodule" a Git submodule usually means one of two things: remove the submodule entirely, or stop treating it as a submodule and keep its files as ordinary tracked files in the main repository. Those are different outcomes, and the commands should match the outcome you actually want.

Understand What a Submodule Adds

A submodule is represented in three places:

• an entry in .gitmodules
• repository configuration in .git/config
• a gitlink entry in the parent repository index

There is also usually a nested repository stored under .git/modules/.... To remove the submodule cleanly, you need to address all of those pieces.

Remove the Submodule Completely

If you want the submodule gone and do not want to keep its contents in the parent repository, the typical sequence is:

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

Then clean up .gitmodules if needed and commit the change.

What this does:

• 'deinit removes the submodule's working-tree configuration'
• 'git rm removes the gitlink and staged submodule path'
• removing .git/modules/... deletes the stored nested repository metadata

Convert the Submodule into Normal Files

If you want to keep the files but stop managing them as a submodule, do not just delete the directory. You need to remove the gitlink relationship and then add the content back as normal tracked files.

A common safe workflow is:

1. copy or preserve the submodule contents
2. deinitialize and remove the submodule linkage
3. restore the files as plain files
4. git add them in the parent repository

The exact commands vary depending on whether you want to preserve history separately, but the conceptual goal is the same: replace the gitlink with normal tracked content.

Check the Result After Cleanup

After removal or conversion, inspect the repository state.

git status
git config --file .gitmodules --get-regexp path || true

You should no longer see the path recognized as a submodule. If the path still appears in .gitmodules or .git/config, the cleanup is incomplete.

Be Careful if Other Clones Depend on the Submodule

Removing a submodule changes repository structure for everyone else. Team members and CI systems may still have submodule initialization logic, update hooks, or deployment assumptions that expect it.

That means the technical cleanup is only part of the job. The repository workflow around that submodule also needs to be updated.

Decide Whether History and Content Need Preservation

Sometimes the real requirement is not just to remove the submodule mechanism, but to preserve the code in place with a clean parent-repository history going forward. That decision should be made before running removal commands, because the cleanup path is different when the content must remain as ordinary tracked files.

Common Pitfalls

• Deleting only the directory and leaving submodule metadata behind.
• Removing the submodule when the real goal was to keep the files as regular tracked content.
• Forgetting to clean .git/modules/..., which leaves stale metadata behind.
• Assuming .gitmodules updates alone are enough.
• Making the structural change without updating CI or teammate setup instructions.

Summary

• "Un-submodule" can mean remove it completely or convert it into normal repository files.
• A submodule exists in the index, config, and module metadata, not only as a directory.
• Use git submodule deinit and git rm for clean removal.
• If you want to keep the content, replace the gitlink with regular tracked files intentionally.
• Verify the cleanup with git status and .gitmodules checks before committing.