What to add to your Gitignore File
What files should you push up into a Git repository? What files should you ignore? These are two questions that plague most beginners when they’re learning about Git.
We’re going to explore these two questions in this article so you’ll never have doubts on whether you should ignore a file in the future.
Let’s begin by understanding why we use Git.
Why we use Git
Git, as you know, is a version control system. We use git to help us track changes we made to our projects to make it easy to backtrack if we made any mistakes.
Since Git is used to track changes, we want to keep the commit history as clean as possible. This means we try not to commit files that can introduce unnecessary conflicts. We also try not to commit files that aren’t needed by the project.
Here’s a rule of thumb I created to help you understand when to ignore a file – A file should be ignored if any of the following is true:
- The file is not used by your project
- The file is not used by anyone else in your team
- The file is generated by another process
Keep this rule of thumb in mind as we walk through the rest of this article. You’ll see why it helps you understand when to ignore a file :)
Now, let’s take a look at common types of files we would ignore. They are:
- Operating system files
- Application files
- Language and framework files
- Files downloaded with package managers
Operating System Files
Operating system files are files that are used by your operating system (like Windows, Mac or Linux). Some examples of these files are
Thumbs.db (on Windows) and
.DS_Store (on Mac).
Thumbs.db is a file that allows Windows to display a thumbnail for each icon in the folder.
.DS_Store on the mac does a similar thing as
Since these files are used for display purposes by your computer, they don’t affect your project in any way. Furthermore, each member of the team likely has their own
Thumbs.db files on their computer, and it’s unlikely that they need yours to work on the project.
If you do commit operating system files into your project, they will become unnecessary changes in the Git commit history. Hence, we ignore operating system files.
Here are some recommended git ignore rules for each operating system:
Hang on to these rules for a while. We’ll come back to them later in the article.
For now, let’s move on to the next category.
Application files are files that are used by applications you installed on your computer. For most developers, these files are files that are generated by code editors. They can also be generated by other applications like Codekit.
Like system files, application files are not required by your project at all. It is also unlikely that any of your team members would require these files in order for them to work on their project. Hence, we ignore application files.
Github has compiled recommended gitignore rules for a list of popular code editors. Take a look and see if you find yours.
Not all editors produce files that are placed in the project folder. If you code editor is not in the list provided by Github, then it’s likely that it doesn’t produce any of such files.
Hold on to these gitignore rules as well. We’ll come back to them later in this article.
Let’s move on to the next category.
Language and Framework Files
Language and framework files refer to files that are generated (or required) by the languages and frameworks you use for your project.
For example, the sass gem produces a
.sass-cache folder whenever it compiles Sass into CSS. Node generates a
npm-debug.log in your project file whenever an error occurs with npm.
Most of the time, these files aren’t required by your project to function, and hence, we don’t need to keep them in the repository.
Once again, Github has been kind enough to compile a list of recommended gitignore items for many languages and frameworks.
Let’s move on to the next category.
Files downloaded with package managers
Package managers are tools to help you download libraries off the web quickly. Popular ones for frontend development are Bower and npm.
Since files that are downloaded with package managers can be re-downloaded quickly by running one command (like
bower install or
npm install), many people feel that they should ignore the
This is indeed what Node recommends. However, Bower suggests that you should check in the
This discrepancy has left many people feeling confused. Thankfully Addy Osmani stepped up and discussed this issue over on his blog.
I recommend that you have a look at Addy’s article to have a clearer picture between the two viewpoints.
Long story short, it’s up to you whether you want to check in the
node_modules folder. I would check them in personally.
Let’s move on to the final category.
Credentials are username and passwords. One example of this file is
wp-config.php, which contains username and passwords for a Wordpress databases.
You don’t want the public to get hold of your credentials at all. Once, I almost had to pay $87,000 to Amazon because a friend accidentally checked my credentials into a public Git repo. Thankfully, Amazon was kind enough to waive this amount off for me.
So um yes. Ignore your credentials if you need to put them in your project repository, or fear having awful consequences like paying $87,000 for nothing.
We’ve covered the five categories of files you should should ignore from your Git repository.
There’s only thing I want to highlight here. Some of the rules we discussed can go into a global
.gitignore file, while others should go into a local
Let’s find out what to put into these two
.gitignore files and how to set them up.
The Global gitignore file
.gitignore file contains rules for ignoring files for every Git repository on your computer. This is a good place to ignore files from the first two categories: Operating System files and Application files.
Let’s create a global
.gitignore file together.
First, create a file in your root folder and name it
$ touch ~/.gitignore_global
Next, open up the
$ open ~/.gitignore_global
Then, paste the rules you obtained in the links from the first two categories into the file. Since I’m on a Mac and I use Sublime Text as my code editor, this is how my
.gitignore_global file looks like:
## Ignore Mac OS Stuff .DS_Store .AppleDouble .LSOverride # Icon must end with two \r Icon # Thumbnails ._* # Files that might appear in the root of a volume .DocumentRevisions-V100 .fseventsd .Spotlight-V100 .TemporaryItems .Trashes .VolumeIcon.icns # Directories potentially created on remote AFP share .AppleDB .AppleDesktop Network Trash Folder Temporary Items .apdisk ## Ignore Sublime text stuff # cache files for sublime text *.tmlanguage.cache *.tmPreferences.cache *.stTheme.cache # workspace files are user-specific *.sublime-workspace # project files should be checked into the repository, unless a significant # proportion of contributors will probably not be using SublimeText *.sublime-project # sftp configuration file sftp-config.json
The final step to the process is to add the
.gitignore_global file to your Git config with the following command:
$ git config --global core.excludesfile ~/.gitignore_global
And we’re done with the
The local gitignore file
.gitignore file is the file we’re used to seeing. It lives in the root of your project folder and contains rules for ignore the rest of the files we mentioned above.
One thing to note here is that many people don’t know about the existence of a global
.gitignore file (I didn’t know about it either). It’s highly possible that they may still check system and application files into your project if you’re not careful about it.
Hence, most local
.gitignore files also contain some rules from system files to mitigate this issue. The two common rules that are used here are
We’re not going to create the local
.gitignore file since you’ll probably know how to do it :)
Let’s wrap the article up now.
In this article, we explored why we use Git, and we understood why we should ignore some files and folders. Then, we discussed the rule of thumb regarding files to be ignored, and went through various categories of files we ignore.
Finally, we learned what to place in both the global and local
That’s the end of this article! Has this article helped clarify your questions on
.gitignore? Let me know what you think in the comments below :)