How to Add Empty Directory to Git Repository

Git doesn’t track empty directories by default because it’s designed to track files rather than folders. To include an empty directory in your Git repository, you need to add a placeholder file like .gitkeep to make the directory non-empty, which allows Git to track it.

Contents

• Why Git Doesn’t Track Empty Directories
• The .gitkeep Solution
• Alternative Approaches
• Best Practices and Implementation
• Common Pitfalls and Troubleshooting

Why Git Doesn’t Track Empty Directories

Git is fundamentally designed to track changes to files, not directories. According to Git Tower’s documentation, “Git does not care about folders - it cares about files. Therefore, if a folder is empty, Git will not offer you to add it to version control.”

This design choice stems from Git’s internal structure, which stores data as a collection of file snapshots rather than directory trees. When a directory contains no files, Git has no meaningful content to track or version, so it simply ignores empty directories during commits and pushes.

Key Insight: Git tracks content, not containers. Without files inside a directory, there’s nothing for Git to actually track or version.

As Mozilla Developer Network explains, this behavior is by design and not a bug. The version control system focuses on actual code and content rather than empty organizational structures.

The .gitkeep Solution

The most common and widely adopted solution is to use a .gitkeep file. According to Stack Overflow, “adding a .gitkeep file (or any other file) to the directory allows Git to include it in version control.”

How to Implement .gitkeep

Here’s the step-by-step process:

1. Create the .gitkeep file in your empty directory:

   bash

   touch my-empty-directory/.gitkeep
   

2. Add the file to Git:

   bash

   git add my-empty-directory/.gitkeep
   

3. Commit the change:

   bash

   git commit -m "Add empty directory structure with .gitkeep"
   

4. Push to remote repository:

   bash

   git push origin main
   

Why .gitkeep Works

The .gitkeep file itself is typically empty and serves no purpose other than to make the directory non-empty. As GitHub Gist explains, “A .gitkeep file tells github to do the opposite of its default behaviour, which is to ignore empty folders.”

The name .gitkeep is a convention that clearly indicates the file’s purpose. While you could name it anything (like .placeholder), .gitkeep has become the industry standard.

Alternative Approaches

While .gitkeep is the most popular solution, there are several alternative approaches you can consider:

1. README.md Files

Instead of .gitkeep, you can add a README.md file to explain the directory’s purpose. As DEV Community suggests, “it’s better practice to add a README.md file in the folder explaining the purpose of the folder.”

Example:

echo "# Empty directory for future components\n\nThis directory will contain components as they are developed." > my-empty-directory/README.md

2. .keep Files

Some teams use .keep files instead of .gitkeep. According to DeployHQ, “By placing a .keep or .gitkeep file inside them, you ensure that they are included in your repository’s history.”

3. .gitignore Configuration

You can configure .gitignore to ignore all files except your placeholder. This approach is mentioned in DesignGurus as maintaining consistency across project directories.

4. Directory Initialization

For directories that will eventually contain files, you can initialize them as Git repositories themselves:

cd my-empty-directory
git init

However, this creates nested repositories, which may not be desirable for all use cases.

Best Practices and Implementation

Choosing the Right Method

Consider these factors when choosing your approach:

Project-Wide Consistency

As DesignGurus emphasizes, “Maintain Consistency: Choose a consistent method for all placeholder directories within your project to avoid confusion.”

Automation Scripts

For teams with many empty directories, you can create automation scripts. As mentioned in Reddit, developers have created Linux scripts to automatically add .gitkeep files to empty directories.

Example script:

#!/bin/bash
# Find all empty directories and add .gitkeep files
find . -type d -empty -exec touch {}/.gitkeep \;
git add .gitkeep
git commit -m "Add .gitkeep files to empty directories"

Version Control Integration

Some modern Git clients and platforms have built-in support for .gitkeep files. They recognize these files as special markers and handle them appropriately during sync operations.

Common Pitfalls and Troubleshooting

Directory Still Not Showing Up

If you’ve added .gitkeep but the directory doesn’t appear in your remote repository, check:

1. Ensure the file is actually committed:

   bash

   git status
   

2. Verify you’re not ignoring the file:

   bash

   git check-ignore my-empty-directory/.gitkeep
   

3. Check your .gitignore rules - make sure you’re not inadvertently excluding the directory or file.

.gitkeep Files in Production

Remember that .gitkeep files serve no purpose in production. You should consider removing them before deployment or adding them to your .gitignore for production builds.

Team Collaboration Issues

Different team members might have different approaches to empty directories. Establish clear guidelines:

• Choose one consistent method
• Document the decision in your project README
• Consider adding a .gitkeep or README file to any new empty directories created

Migration from Other Version Control Systems

Teams migrating from SVN might expect different behavior. As mentioned in Reddit, “Although I love git, as everyone else, there are some undesirable” differences from SVN’s approach to directory tracking.

Conclusion

Adding empty directories to Git requires understanding that Git fundamentally tracks files rather than containers. The .gitkeep solution has emerged as the industry-standard approach, providing a simple, elegant way to preserve directory structure while maintaining Git’s file-centric design.

Key takeaways:

1. Git doesn’t track empty directories by design - this is expected behavior, not a bug
2. The .gitkeep file method is the most widely adopted solution
3. Consider alternative approaches like README.md files depending on your project’s needs
4. Maintain consistency across your project to avoid confusion
5. Remember that .gitkeep files serve no functional purpose - they’re purely structural markers

For most development scenarios, adding a .gitkeep file to empty directories will solve the problem effectively while keeping your repository clean and organized. This approach ensures that your directory structure remains intact during deployments and collaborations, exactly as DeployHQ explains.

Sources

1. How can I add an empty folder to version control in Git? | Git Tower
2. How do I add an empty directory to a Git repository? - Stack Overflow
3. Track Empty Directories with git - David Walsh
4. How to Add an Empty Directory in Git {Step-by-Step Guide} - phoenixNAP
5. How to add an empty directory in git - Graphite
6. Understanding .keep and .gitkeep Files: A Guide - DeployHQ
7. What is .gitkeep? How to Track and Push Empty Folders in Git - FreeCodeCamp
8. .gitkeep - Push your entire folder structure to GitHub, including empty folders - GitHub Gist
9. How do I add an empty directory to a Git repository? - DesignGurus
10. What is .gitkeep? How to Track and Push Empty Folders in Git - Bomberbot