An empty folder disappears from a Git clone: track a deliberate placeholder
By ON Lab · Sources checked November 8, 2026
In ordinary Git add and checkout workflows, an empty directory does not create a tracked file entry. If you need its path to appear in a fresh checkout, track a deliberate placeholder file inside it or create the directory through the project's setup process. Verify the tracked entry and a fresh checkout; a successful git add alone is insufficient.
The historical reader asked how to add a directory containing no files. We checked Git's add documentation and Canonical's explanation of empty directories in git-ubuntu, then tested normal add, commit and local clone operations. This guide concerns the ordinary index-based workflow. It does not claim that Git's low-level object format is unable to represent an empty tree.
Confirm that the directory is actually empty
A file browser can hide dotfiles, and a directory can contain ignored files even when ordinary status appears quiet. Inspect the intended path and use a narrow tracked-file query:
git ls-files -- "expected-directory"An empty result means this query listed no tracked file under that path. It does not prove that the filesystem directory contains nothing, that it is not ignored or that another application has no files open there. Keep those questions separate.
What our add and clone test showed
We initialized a disposable repository and created a directory named empty. Running git add empty exited successfully, but a subsequent git ls-files -- empty still returned no entry. The empty directory itself had not become a file tracked through the index.
We then created an empty file named .gitkeep inside that directory, added that exact file and checked the index again. It listed empty/.gitkeep. After committing the file and cloning the local repository into a new directory, the cloned placeholder existed at the expected path.
| Check | Observed result |
|---|---|
| Add the empty directory | Exit 0, no tracked file entry |
| Add its placeholder | Placeholder appears in ls-files |
| Commit and make a local clone | Placeholder and containing path exist in the clone |
The verification read the new checkout rather than assuming the commit command guaranteed the desired layout. No remote repository, hosting account or real project was changed.
Choose a placeholder intentionally
.gitkeep is a common naming convention, not a special Git instruction that automatically preserves a directory. A tracked README explaining the directory's purpose can serve the same layout goal. Choose the convention your project already uses.
Create a new placeholder without overwriting an existing file, then add its exact path and inspect the staged diff. In a POSIX shell, a possible workflow after creating the reviewed file is:
git add -- "expected-directory/.gitkeep"
git diff --cached --stat
git ls-files -- "expected-directory"Do not stage the entire repository merely to preserve one folder. A placeholder does not make later generated files automatically ignored. If generated content should stay untracked, define and review the appropriate ignore policy separately. If the placeholder itself is unexpectedly ignored, locate the matching ignore rule before deciding whether an exception is appropriate.
A placeholder means the directory is not empty
Some tools need a directory to exist but permit a small placeholder. Other tools require a genuinely empty directory, reject unexpected files or produce their own managed directory structure. A placeholder is not equivalent to emptiness for those applications.
Canonical's git-ubuntu documentation discusses this distinction for source packages: the presence or absence of empty directories can matter to a build, and ordinary index and checkout behavior differs from low-level tree representation. Do not apply a placeholder convention to an importer or packaging workflow without checking its own contract.
If a directory must be genuinely empty at runtime, create it through the documented setup or build step, and test that setup in a clean checkout. That records an instruction to produce the directory, rather than pretending the placeholder is invisible to the application.
Verify the actual outcome
- Confirm which files, if any, are tracked under the path.
- Choose a placeholder or setup step based on the application's requirements.
- Review and commit only the intended change through the project's normal process.
- Use a separate clean checkout to verify the directory layout.
- Run the relevant setup or application check if true emptiness matters.
If the path is a submodule, an apparently empty folder can have a different cause. The submodule initialization guide handles fetching the recorded nested checkout. Adding a placeholder to an uninitialized submodule is not the same repair.
Checked November 8, 2026. The normal add/index/commit/local-clone comparison was executed. Low-level empty-tree construction, git-ubuntu import operations and a reader's actual build system were not tested. Historical reader evidence is not measured search demand.