Add an empty directory to a Git repository

Normal Git workflows do not track empty directories. Add a small placeholder file inside the directory if you want it to appear in a fresh checkout. .gitkeep is a naming convention, not a special Git feature.

Add a placeholder

mkdir -p uploads
touch uploads/.gitkeep
git add uploads/.gitkeep
git commit -m "Keep uploads directory in checkouts"

The directory is now represented by a tracked file. .keep works equally well, and a README.md can explain what belongs there. Choose a convention that fits the project.

Ignore generated contents but keep the placeholder

Put these rules in the repository-root .gitignore:

uploads/*
!uploads/.gitkeep

Then commit the ignore file as well. New uploaded files stay untracked, while the placeholder gives other developers the directory structure after cloning.

Do not replace the first rule with uploads/ and expect the exception to work: ignoring the entire parent directory prevents Git from re-including a file inside it. Existing tracked files are not affected by ignore rules.

An alternative is to put a .gitignore inside uploads itself:

*
!.gitignore

The ignore file then serves as the tracked placeholder.

Create the directory during setup instead

If a build or application already has a setup step, it can create the required directory:

mkdir -p uploads

This can be clearer for temporary, cache, or runtime directories that should be created with deployment-specific ownership and permissions. A tracked placeholder guarantees a path in the checkout, not that the application can write to it.

FAQ

Is Git's object model unable to represent empty trees?

No. Empty tree objects exist. The limitation here is the normal index and checkout workflow, which records file paths rather than tracking empty directories as independent entries.

Does the placeholder affect the application?

Usually it is harmless, but it is still a real file. Code that processes every directory entry, checks whether a directory is empty, or uploads all contents should exclude it when appropriate.

Which name should we use?

Git gives .gitkeep, .keep, and README.md no special directory-preserving behavior. Tracking any of them has the same basic effect; an explanatory README can be more useful than an empty file.

See git-add, gitignore, and Git's object model.