what and where to .gitignore

I stumbled over a tweet of a friend of mine that sums up my feelings about what to add to a .gitignore file pretty well.

And then a debate spun up from that with the core-message that people need to know about the different ways to ignore files from automated inclusion in git-commits.

So let’s have a look at that.

git allows us to use three different ways to ignore files:

Project-specific gitignore-file

The probably best known way is by adding the filename to a file named .gitignore within the project. You can even use more than one .gitignore-File by adding one to different folders (though for obvious reasons you can only use one file per folder). Whether to use one or multiple .gitignore-files is a different discussion altogether.

This is the file the whole discussion spun around. This file should (note the conjunctive here) only be used for files that are related to your project. To give you an example imagine that you have a file .env.dist that contains a template of a .env file. Each contributor creates the .env file by copying the .env.dist and then editing it by adding credentials etc. Those credentials should never be added to the repo. So you can add the .env fiel to the projects .gitignore-file to make sure that git ignores that file. As the gitignore-file is committed it will be distributed to every contributor.

Project-specific exclude-file

Additionally you can add files to a file .git/info/exclude. That file is inside your git-folder and will therefore not be committed. So this is the best place to add files that you personally might need for your contributions but that are not relevant to everyone else. I usually have some executables in it that I created for the project but that are specific to my personal workflow. I don’t want anyone else to use them as they are hacky automation stuff but they are specific to the project.

Global gitignore-file

And finally there is a global .gitignore-file. To check where your global gitignore-file is located run this command:

git config core.excludesfile

Usually it is something like ~/.gitignore but it can be anything. Sometimes it can even be none which means that it is not configured. In that case feel free to consult your favourite search engine to find a tutorial on how to setup a global gitignore file.

This global gitignore-file is important to be able to automatically ignore all the files that are special to your personal setup but not project-specific. What files could that be, you might ask yourself now. Well: For example Apples feared .DS-Store files. Or your editors configuration files. Or your editors temporary or lock files. There are so many different possibilities. To get a general idea, you might want to have a look at gitignore.io – and the fact that there is a SAAS to generate gitignore-files shows how complicated it can be…

The great thing about this global gitignore-file is, that it applies in every git-project on your machine! So once configured it will work in every git-folder. Even in new projects that do not yet have a local .gitignore-file. And you can now safely commit code without fear that special files from your personal setup are accidentally committed.

Why all this fuss?

Well. One can of course add all the possible (and impossible?) files that certain IDEs or Editors add to your project to the project-specific .gitignore-file. But that means either having a very large file as you need to take all possibilities into account. Or it means (and that can also happen with a huge .gitignore-file) that you possibly miss something.

And imagine an editor-vendor renaming their config-setup. Or a new Editor starts to become en vogue. Now everyone needs to modify their .gitignore-files in their projects as someone might be able to commit a wrong file.

One way to make sure that no unwanted files enter a projects git-repo is to do code-reviews. Automation can help with spotting unwanted files, but it will never be able to spot all possibilities. Make sure that your code-review process spots those unwanted files.

And as a committer I will always need to be careful when committing! So before committing I should always check, that only files that I actually want to commit are committed! So I either have a look at the documentation of my Editor/IDE/Git-GUI or I use the CLI to specifically add the files. And I love git add -p – but that’s probably another blog-post.

For more infos have a look at the official documentation. And here and here are examples of project-specific .gitignore-files.