Introduction

Git cannot simply "convert" a normal tracked directory into a submodule with one command. A submodule is a separate Git repository recorded by the parent repository as a commit reference, so the real workflow is to extract that directory into its own repo, remove the old tracked directory from the parent, and add the new repo back as a submodule at the same path.

Why an Existing Folder Is Not Already a Submodule

A regular directory inside a repository is just part of the parent repo's tree. A submodule is different:

• It has its own .git data and commit history
• The parent repo stores only a pointer to a specific submodule commit
• Clones of the parent repo do not automatically contain the submodule contents unless initialized

That difference is why you cannot run a command that simply toggles a folder from one state into the other while keeping everything in place.

Preserve the Folder History With git subtree split

If the directory already has meaningful history in the parent repository, the cleanest extraction path is to split that history into its own branch first.

# from the parent repository root
git subtree split --prefix=libs/shared -b split-shared

That creates a branch containing only the history of libs/shared. You can then push it into a new standalone repository:

1git clone . /tmp/shared-repo
2cd /tmp/shared-repo
3git checkout split-shared
4git remote add origin [email protected]:your-org/shared.git
5git push -u origin split-shared:main

At this point, libs/shared has become a real repository with its own history rather than just a copied folder.

Replace the Old Directory in the Parent Repo

Once the standalone repository exists, remove the tracked directory from the parent repository and commit that change.

cd /path/to/parent-repo
git rm -r libs/shared
git commit -m "Remove in-repo shared directory before submodule conversion"

Now add the new repository back as a submodule at the same path:

git submodule add [email protected]:your-org/shared.git libs/shared
git commit -m "Add shared repository as submodule"

The folder path stays the same, but its meaning changes. Instead of storing all file contents directly, the parent repo now tracks a specific commit from the child repository.

Simpler Option if History Does Not Matter

If you do not need to preserve the folder's old history, the process is shorter:

1. Copy the folder contents into a new repository manually.
2. Commit and push that repository.
3. Remove the original directory from the parent repo.
4. Add the new repository as a submodule.

That approach is easier, but you lose the old per-file history tied to the original path inside the parent repository.

Working With the New Submodule

After the conversion, collaborators need to initialize submodules when cloning:

git clone [email protected]:your-org/parent.git
cd parent
git submodule update --init --recursive

When the submodule changes later, you commit inside the submodule repository first, then commit the updated submodule pointer in the parent repository.

Common Pitfalls

• Trying to add the submodule on top of still-tracked files causes conflicts because Git sees both the old directory and the new submodule path.
• Forgetting to push the standalone repository before adding the submodule leaves collaborators with a broken reference.
• Assuming submodules behave like copied folders leads to confusion. They are commit pointers, not embedded snapshots you edit casually from the parent repo.
• Skipping git submodule update --init --recursive after cloning makes the directory look empty or incomplete.

Summary

• You cannot directly flip a tracked directory into a submodule in place.
• The usual path is extract history into a new repo, remove the old directory, then add the new repo as a submodule.
• Use git subtree split when you want to preserve the folder's history.
• After conversion, remember that the parent repo tracks a submodule commit, not the full folder contents.