Why .gitkeep Is Unnecessary: A Better Way to Track Empty Directories in Git

When you clone a fresh repository, empty folders simply disappear because Git only tracks files. Many developers resort to creating a placeholder file called .gitkeep to force Git to create the directory. While this works, the approach adds extra maintenance overhead. In a recent post, Adam Johnson argues that a .gitkeep file is unnecessary and recommends using a .gitignore‑only strategy instead. This article expands on that idea, provides step‑by‑step commands, and shows why the simpler method aligns with modern Git best practices for developers, DevOps engineers, and technical writers.

Why .gitkeep Became Popular

The .gitkeep convention emerged because Git cannot track empty directories. By adding an empty file named .gitkeep inside the folder, the directory becomes non‑empty and therefore versioned. The file name is purely conventional; Git treats it like any other file.

The Drawbacks of the .gitkeep Technique

• Two files to maintain: the placeholder and a matching rule in the root .gitignore.
• Renaming the directory requires updating the ignore pattern, a step that’s easy to miss.
• The name .gitkeep is not an official Git feature, so new team members may be confused.
• Extra commit noise – the placeholder adds no functional value.

The .gitignore‑only Solution

Instead of a placeholder, place a minimal .gitignore file inside the empty directory. The file contains two lines:

*
.gitignore

The first line tells Git to ignore everything in the folder; the second line re‑includes the .gitignore itself, allowing it to be committed. This single file guarantees the directory’s existence in every clone without the overhead of a separate placeholder.

Step‑by‑Step: Implementing the .gitignore‑only Method

1. Create the target directory.

   mkdir -p build

2. Add a .gitignore file inside it. Use a single command to write the two required lines:

   echo '*\n.gitignore' > build/.gitignore

3. Stage and commit the directory.

   git add build/.gitignore
   git commit -m "Track empty build directory with .gitignore"

4. Verify the result. Run git status to see that only the .gitignore file is tracked:

   git status
   # On branch main
   # Changes to be committed:
   #   new file:   build/.gitignore

5. Push to remote. The empty folder will now appear for anyone who clones the repo:

   git push origin main

If you later need to add real files to build/, simply remove the * line or add more specific ignore rules. The directory remains tracked because the .gitignore file is already part of the history.

Benefits of Using .gitignore‑only

• Single source of truth: Only one file needs to be edited, reducing the chance of mismatched ignore patterns.
• Zero‑maintenance on rename: Moving the folder automatically moves its .gitignore, so no extra updates are required.
• Clear intent: Anyone reading the repository sees a standard .gitignore and instantly understands that the folder is meant to stay empty.
• Cleaner commit history: No placeholder files clutter the diff view.
• Better tooling support: IDEs and Git GUIs recognize .gitignore files natively, offering syntax highlighting and validation.

Applying the Technique in AI‑Driven Projects

Many modern SaaS products built on the UBOS platform overview generate temporary data folders (e.g., logs/, temp/) that must exist after deployment but should stay empty in source control. Using the .gitignore‑only pattern keeps those directories versioned without polluting the repo with dummy files.

For example, a OpenAI ChatGPT integration might write user prompts to a cache/ folder at runtime. By adding a .gitignore inside cache/, developers ensure the folder is created on every fresh clone, while the actual cache files remain untracked.

Similarly, when building a ChatGPT and Telegram integration, you may need a webhooks/ directory for incoming payloads. The same technique guarantees the directory structure is present for both local testing and production deployments.

Quick Reference: .gitkeep vs .gitignore‑only