Introduction

A Git repository inside another repository can be intentional or accidental, and the correct workflow depends on which it is. If the inner project should keep its own history, you usually want a submodule or subtree. If it should just be ordinary files in the outer repository, remove the inner .git metadata and track the files normally.

What Git Sees in a Nested Repository

When a repository contains another directory that itself has a .git directory, Git treats that inner directory as an embedded repository rather than automatically folding its history into the outer one.

That is why git add often warns about an embedded repository. The outer repository can record a reference to the inner repo, but it does not magically absorb the inner commit history.

Option 1: Use a Submodule

Submodules keep the inner project as a separate repository and let the outer repository point to a specific commit of it.

git submodule add https://example.com/lib.git vendor/lib
git commit -m "Add lib as submodule"

This is appropriate when the inner project:

• has its own lifecycle
• should keep its own remote
• should be version-pinned by the outer project

To clone later with submodules:

git clone --recurse-submodules https://example.com/app.git

Or initialize them in an existing clone:

git submodule update --init --recursive

Option 2: Use a Subtree

Subtrees copy another repository into a subdirectory while keeping the workflow more integrated for the outer repo.

git subtree add --prefix=vendor/lib https://example.com/lib.git main --squash

Later updates can be pulled with:

git subtree pull --prefix=vendor/lib https://example.com/lib.git main --squash

Subtrees are often easier for teams because contributors do not need special submodule commands after cloning.

Option 3: It Was Accidental

Sometimes the nested repository was never meant to remain independent. In that case, remove the inner .git directory and commit the files as ordinary content in the outer repository.

rm -rf path/to/inner-project/.git
git add path/to/inner-project
git commit -m "Track inner project as regular files"

Only do this if you are sure you do not need the inner repository to keep functioning as a separate Git repo in place.

How to Choose

A practical rule:

• use a submodule when the inner repository should remain clearly separate
• use a subtree when you want a more seamless outer-repo workflow
• remove the inner .git directory when the nesting was accidental

The right choice depends on whether separation or convenience matters more for the project.

Common Pitfalls

The biggest pitfall is copying a repository into another repository and assuming the outer git add . will capture everything cleanly. It will not preserve the inner history the way most people expect.

Another common mistake is choosing submodules without documenting the required clone and update commands for teammates. Submodules are valid, but they require more operational discipline.

Developers also sometimes leave accidental nested repositories in place for months, which causes confusing Git warnings and incomplete clones for other contributors.

Summary

• A repository inside another repository should be handled intentionally, not left as an accidental embedded repo.
• Use submodules when the inner repository must stay independent and pinned.
• Use subtrees when you want a more integrated outer-repo workflow.
• Remove the inner .git directory if the nested repository was accidental and should become regular files.
• Git's embedded-repository warning is a signal to choose a deliberate structure.