Introduction

Maintaining one Git repository inside another is possible, but you should choose the structure deliberately. The three common options are a plain nested repo that the outer repo ignores, a submodule when the inner repo should remain independent, or a subtree when you want to vendor another repo while keeping a simpler top-level workflow.

Understand The Three Main Approaches

These approaches solve different problems.

A plain nested repository means:

• the inner directory has its own .git
• the outer repository should usually ignore that directory
• the histories stay completely separate

A submodule means:

• the outer repository tracks a specific commit of the inner repository
• the inner project remains an independent repository
• collaborators must initialize and update submodules

A subtree means:

• the other repository's files are copied into the outer repository history
• there is no separate .git directory inside
• the top-level clone experience is usually simpler

The right answer depends on how tightly coupled the projects are.

Plain Nested Repo For Local Independence

If the inner repo is just a local tool or independent project and the outer repo should not track its contents, ignore the directory:

tools/my-inner-repo/

Then initialize or keep the inner repo normally:

cd tools/my-inner-repo
git init

This works, but the outer repo sees the inner folder as just an ignored directory. There is no relationship between the histories.

That is fine for purely local setups, but not great if teammates need the same nested project automatically.

Use A Submodule For A Real Nested Repository

If the inner project has its own lifecycle and should stay a true independent repository, submodules are the standard Git mechanism.

Add one like this:

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

Clone with:

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

Update later with:

git submodule update --init --recursive

The outer repo stores a pointer to a specific commit of the inner repo, not a full copy of its working history as regular files.

Submodules are a good fit when the nested project is genuinely independent and may be shared by multiple parent repositories.

Use A Subtree For Easier Top-Level Workflows

If you want another repository's contents inside your project without forcing collaborators to manage submodule commands, subtree is often easier.

Example:

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

This imports the files into the main repository history.

Later updates:

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

Subtree is a good compromise when:

• you want one normal clone
• you do not want nested .git directories
• the dependency can be vendored as files

The downside is that the relationship is less obvious than a submodule pointer, and pushing changes back upstream requires more discipline.

Avoid Accidental Nested Repositories

Sometimes a nested repo appears by mistake because someone copied a project folder with its .git directory into another repo. That usually causes confusion:

• the outer repo does not track the inner files as expected
• 'git status shows odd results'
• teammates do not realize there are two histories

If the nested history is not intentional, remove or rename the inner .git directory and decide whether the files should become normal tracked files, a submodule, or a subtree import.

Pick Based On Maintenance Burden

A practical rule:

• use a plain ignored nested repo for purely local independent work
• use a submodule for a true shared dependency with separate history
• use a subtree when you want simpler consumption inside the main repo

What you should not do is keep an accidental repo-inside-repo setup with no documented reason. That is where most maintenance pain comes from.

Common Pitfalls

The biggest mistake is copying a repository into another repository and assuming Git will just "handle it." A nested .git directory changes the tracking model completely.

Another mistake is choosing submodules without planning for collaborator workflow. They work well, but only if the team consistently initializes, updates, and commits the submodule pointer correctly.

People also choose subtrees and then forget where the imported code originally came from. Document the upstream source and update procedure clearly.

Finally, do not ignore the maintenance story. The right nesting strategy is less about what Git can do and more about what your team can operate cleanly over time.

Summary

• A repo inside another repo is possible, but you should choose the relationship intentionally.
• Use an ignored nested repo for local independence, a submodule for true separate history, or a subtree for simpler top-level usage.
• Submodules track a commit pointer to another repository.
• Subtrees vendor files into the parent repository history.
• Accidental nested .git directories are usually a sign to stop and choose a cleaner structure.