Git: 'warning: adding embedded git repository', a repository inside a repository

warning: adding embedded git repository: libs/charts means the folder you added has its own .git folder, so Git recorded only a pointer to one of its commits, not its files. Decide what you meant: if the files belong to this repository, unstage the pointer, move the inner .git away and add the folder again; if it is a separate project, add it properly with git submodule add.

It is only a warning, so git add succeeds and the commit goes through. The trouble shows up later, when a teammate clones the repository and finds the folder empty.

The error

PS> git add .
warning: adding embedded git repository: libs/charts
hint: You've added another git repository inside your current repository.
hint: Clones of the outer repository will not contain the contents of
hint: the embedded repository and will not know how to obtain it.
hint: If you meant to add a submodule, use:
hint:
hint: 	git submodule add <url> libs/charts
hint:
hint: If you added this path by mistake, you can remove it from the
hint: index with:
hint:
hint: 	git rm --cached libs/charts
hint:
hint: See "git help submodule" for more information.
hint: Disable this message with "git config advice.addEmbeddedRepo false"

Why it happens

Git never stores another repository's .git folder. When git add meets a folder that is itself a repository, it stores a single entry of the special mode 160000, a "gitlink" holding the commit that inner repository is on, and nothing else. The index shows it plainly:

PS> git ls-files --stage
100644 b890f3d753bf2242c2d252fa246db00b3224c01d 0	app.txt
160000 4d933905c1dd0eb0e9640053ec3a14ce91793ab1 0	libs/charts

A real submodule also has a .gitmodules file that says where to clone that commit from. Here there is none, so a clone gets an empty libs/charts and no way to fill it. The usual causes are running git init in a subfolder by mistake, copying in a project that you cloned, or a tool that scaffolds a new project with its own repository inside an existing one.

The fix

The files belong to this repository: drop the gitlink, move the inner .git aside, add the folder again.

PS> git rm --cached libs/charts
rm 'libs/charts'
PS> Move-Item libs\charts\.git ..\a6-charts-git-aside
PS> git add libs/charts
PS> git status --short
D  libs/charts
A  libs/charts/chart.txt
PS> git commit -q -m "charts as plain files"
PS> git ls-files --stage
100644 b890f3d753bf2242c2d252fa246db00b3224c01d 0	app.txt
100644 5756c9e25a7bc6b5bd3daad39a1ab04c8912ecef 0	libs/charts/chart.txt

Moving the inner .git rather than deleting it keeps its history in case you want it later. The files are now ordinary tracked files (mode 100644). If the folder really is a separate project with its own history, make it a submodule instead, so the URL is recorded in .gitmodules. In a repository where the embedded folder was already committed, the path has to be freed first: unstage the gitlink and move the inner repository folder out, then add the submodule from the project's URL (here a local copy of the same project):

PS> git rm --cached libs/charts
rm 'libs/charts'
PS> Move-Item libs\charts ..\c6-charts-moved
PS> git -c protocol.file.allow=always submodule add ../a6-charts-src libs/charts
PS> git status --short
A  .gitmodules
M  libs/charts

The -c protocol.file.allow=always part is needed only because the test used a local folder as the submodule URL; with an https or ssh URL, leave it out.

How it was reproduced

Git for Windows 2.45.2 on Windows 11, Windows PowerShell 5.1. A throwaway repository got a subfolder libs/charts in which git init and one commit were run; git add . in the outer repository printed the warning with exit code 0 and the commit stored a 160000 entry. Both fixes were run on such a committed embedded folder (each in its own repository) and checked with git ls-files --stage.

Frequently asked

Why is my folder empty after cloning a git repository?

The folder was committed as an embedded repository: Git stored only a pointer to a commit of the inner repository, not its files. Fix it in the original repository with git rm --cached and add the files again, or make it a submodule.

How do I remove an embedded git repository from the index?

Run git rm --cached on the folder path, as the hint shows. Then move the inner .git folder away and git add the folder to track its files normally.

Should I use a submodule or just add the files?

Use a submodule when the folder is a separate project with its own history and release cycle. Add the files directly when they belong only to this repository.

More decoded errors in the Fixes category. If the folder shows up but its files stay ignored for another reason, see .gitignore not working.