Why you should always .gitkeep

You should always use .gitkeep (i.e. create an empty .gitkeep file in the respective directory) when you want to check in empty directories to git!

You find yourself in the following situation: You’ve just started a new project, you are excited and want to get the busy work out of the way. As such, you take the first step and start creating the folder structure for your project.

Because version control is important to you, you start off by using git init to initialize the directory as a git repository.

You create the folder structure, which might look something like this:

• src
• doc

You are done with creating the folder structure, now all that remains is to commit this change to the repository.

You run git add . to add everything but you notice a strange message from git:

nothing to commit (create/copy files and use “git add” to track)

The message exactly explains what is the problem.

Create/copy files and use “git add” to track.

Git can’t track empty directories. The solution is simple though: Just add an empty file to each of the empty directories. Then you can add the empty files to git and with them, the directories will also be added.

You rush off to create the empty files. You just add a simple name for the empty files, something like “a.txt”. Your directory structure looks like this now:

.
├── doc
│ └── a.txt
└── src
 └── a.txt

You don’t notice it now, but there is a problem with this approach. A general rule in programming is to give meaningful names. The file name “a.txt” violates this rule. Why is the empty file “a.txt” there? What does it do? Could you guess it if you were to only look at the name? Probably not. But why is that a problem? You will just delete a.txt as soon as you add some meaningful files to the directories… Right? You definitely should, but maybe you will forget.

Let’s say that you forgot to delete the file and you continue working on your project. You invite other people to collaborate as well. Your project grows. After a while you get bored of the project and don’t want to contribute to it anymore. Other people take over. Then some day a newbie comes who finds the project really interesting and wants to contribute to it. He starts browsing the code and finds a bunch of “a.txt” named empty files. He is confused as to what these do. He is new to the project and doesn’t want to mess up anything, so he leaves them there. What could deleting these empty files cause? Will the builds fail because of this change? Will the production system break? Will deleting it cause a nuclear apocalypse? Probably not, but he doesn’t know that for sure :).

What if I told you, that there is a way to avoid all of this confusion by just naming the file correctly. Why is the file there? So that git will keep the otherwise empty directory in version control. As such, you should name the file “.gitkeep”. There is also a convention of using this file name in these cases. People know about .gitkeep, or if they don’t, they can google it and they will soon find out why it’s there.

The moral of this story is to:

• Give meaningful names! Even in such trivial cases, where you only want to check in an empty directory. It costs you max. 5 minutes to give a meaningful name, but it saves a LOT of time for the people that work on the project after you’re gone.
• Clean up after yourself! Don’t leave unused files in the code repository.