How to create git ignore files

3 July 2021
Gary Woodfine
10 min read

We have previously gone through the process of how to install Git and explored some of the advanced git configuration options, then progressed on how to create a git repository.

In this post, we're going to look at how we can do some configuration to control and ensure certain types of files and directories are not included into our git repository. Often when creating Git based version control repositories, there will be certain types of files or even folders that you will want to exclude from being controlled and managed within your repository. These could be files that could be generated by your project at run time or output from various processes. Integrated Development Environments (IDE) and Operating Systems (OS) also generate hidden files and system generated file which should also be excluded from repositories.

Git makes this job really easy for you by enabling you to create what is known as a Git Ignore file.

What is the .gitignore file

A .gitignore file is essentially a text-based file that developers can use to list specific files, file types and folders to be excluded from being added or managed by a git repository.

Git is a popular version control system provides the ability to create a Global and Local and these have very specific purposes and developers should definitely making use of both these ignore file options on their development workstations.

What is a Global Git ignore file

All the popular OS (Linux, Mac OS and Windows) often create hidden files in directories that will often contain metadata and other information which you typically don't want to include in a git repository. These not only add clutter to your git repository, but they could potentially leak sensitive information. Developers should also exclude files and directories created by their favourite tools and frameworks that are not necessary to be included.

All these files and directories could be added to a local .gitignore file to be excluded, but this is not regarded as best practice. Due in part, that it becomes complicated and does clutter your project specific git ignore file with all the various OS specific and Tool specific file types.

Most developers will be creating and sharing hundreds of git repositories and having to remember copying these settings over project to project is less than ideal. Fortunately, git enables you to create a Global .gitignore file which is respected by git throughout your User Directory with rules that should be applied to every git repository.

This is usually achieved by creating a hidden file in your Home directory with rules that are specific to your system. A global .gitignore file is best used for common files like .env , .DS_Store , node_modules etc which you will almost never want to commit to a git repository.

How to create a Global Git ignore File

We mentioned earlier that a .gitignore is just really a simple text-based file and they are really simple to create. In this example we'll create a Global .gitignore using the terminal window , in our user home directory.

touch $HOME/.gitignore

This will have created a blank hidden .gitignore in our Home directory. We verify that it exists by :

ls - a $HOME

.gitignore file in directory

We can now populate this file with our environment specific data that we would like to exclude from any new or existing repositories we create and use on our machine. Github provide a very useful collection of useful Global .gitignore templates you can use to tailor your global file.

In my particular case, I predominantly use Jetbrains Based IDE's and Tools such as WebStorm, Rider, PHPStorm, GoLand etc. on Linux based computers. So typically use the defaults that are provided in Jetbrains Ignore and the Linux Ignore file settings. Occasionally I may do this by opening the new created .gitinore in my preferred text editor and pasting the values defined below in. However, I have mostly use my own automated process to create git ignore files

nano $HOME/.gitignore

The values I typically include are:

# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839

# User-specific stuff
.idea/**/workspace.xml
.idea/**/tasks.xml
.idea/**/usage.statistics.xml
.idea/**/dictionaries
.idea/**/shelf

# Generated files
.idea/**/contentModel.xml

# Sensitive or high-churn files
.idea/**/dataSources/
.idea/**/dataSources.ids
.idea/**/dataSources.local.xml
.idea/**/sqlDataSources.xml
.idea/**/dynamic.xml
.idea/**/uiDesigner.xml
.idea/**/dbnavigator.xml

# Gradle
.idea/**/gradle.xml
.idea/**/libraries

# Gradle and Maven with auto-import
# When using Gradle or Maven with auto-import, you should exclude module files,
# since they will be recreated, and may cause churn.  Uncomment if using
# auto-import.
# .idea/artifacts
# .idea/compiler.xml
# .idea/jarRepositories.xml
# .idea/modules.xml
# .idea/*.iml
# .idea/modules
# *.iml
# *.ipr

# CMake
cmake-build-*/

# Mongo Explorer plugin
.idea/**/mongoSettings.xml

# File-based project format
*.iws

# IntelliJ
out/

# mpeltonen/sbt-idea plugin
.idea_modules/

# JIRA plugin
atlassian-ide-plugin.xml

# Cursive Clojure plugin
.idea/replstate.xml

# Crashlytics plugin (for Android Studio and IntelliJ)
com_crashlytics_export_strings.xml
crashlytics.properties
crashlytics-build.properties
fabric.properties

# Editor-based Rest Client
.idea/httpRequests

# Android studio 3.1+ serialized cache file
.idea/caches/build_file_checksums.ser

*~

# temporary files which can be created if a process still has a handle open of a deleted file
.fuse_hidden*

# KDE directory preferences
.directory

# Linux trash folder which might appear on any partition or disk
.Trash-*

# .nfs files are created when an open file is removed but is still being accessed
.nfs*

Once we have finished creating our file, we now need to configure Git to make use of it. We do so by using the following command

git config ---global core.excludesfile ~/.gitignore

These settings are now recognised and respected throughout all git repositories on your machine. However, the global git ignore file shouldn't be considered a great solution for all your collaborative repositories, because undoubtedly other developers on your team etc may not actually set this up or they may have a completely different settings as you.

What is a local Git ignore file

A local .gitignore file is usually placed in the root directory of a project and will contain project specific settings pertaining to the files and directories you wish to exclude from your project.

Each line in a git ignore file specifies a pattern. When deciding whether to ignore a path, Git normally checks git ignore patterns from multiple sources, with the following order of precedence, from highest to lowest.

Patterns read from a .gitignore file in the same directory as the path, or in any parent directory, with patterns in the higher level files (up to the top level of the work tree) being overridden by those in lower level files down to the directory containing the file. These patterns match relative to the location of the .gitignore file. A project normally includes such .gitignore files in its repository, containing patterns for files generated as part of the project build.

How to create a local Git ignore file

The process of creating a local git ignore file is the same as creating is similar to the global git ignore, in that you just create a text based file named .gitignore file in your project directory. Then include the settings you wish. However, personally I find the process of creating git ignore files tedious and boring and like all programmers should I have created an automated process to accomplish this task.

As we mentioned earlier Githib provides a collection of useful .gitignore templates to use for creating your gitignore file. By making use of a simple Curl command to download the version of gitignore file we want from the repository. For instance if want to create a typical .gitignore for a NodeJS project we simply execute the following cUrl command in our terminal window

curl -o .gitignore  https://raw.githubusercontent.com/github/gitignore/master/Node.gitignore

This will download the Node .gitIgnore file to our directory and save it as .gitignore. If we inspect the content of this file it contains the all the typical git ignore rules for NodeJS based projects.

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

# Runtime data
pids
*.pid
*.seed
*.pid.lock

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage
*.lcov

# nyc test coverage
.nyc_output

# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt

# Bower dependency directory (https://bower.io/)
bower_components

# node-waf configuration
.lock-wscript

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules/
jspm_packages/

# Snowpack dependency directory (https://snowpack.dev/)
web_modules/

# TypeScript cache
*.tsbuildinfo

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Microbundle cache
.rpt2_cache/
.rts2_cache_cjs/
.rts2_cache_es/
.rts2_cache_umd/

# Optional REPL history
.node_repl_history

# Output of 'npm pack'
*.tgz

# Yarn Integrity file
.yarn-integrity

# dotenv environment variables file
.env
.env.test

# parcel-bundler cache (https://parceljs.org/)
.cache
.parcel-cache

# Next.js build output
.next
out

# Nuxt.js build / generate output
.nuxt
dist

# Gatsby files
.cache/
# Comment in the public line in if your project uses Gatsby and not Next.js
# https://nextjs.org/blog/next-9-1#public-directory-support
# public

# vuepress build output
.vuepress/dist

# Serverless directories
.serverless/

# FuseBox cache
.fusebox/

# DynamoDB Local files
.dynamodb/

# TernJS port file
.tern-port

# Stores VSCode versions used for testing VSCode extensions
.vscode-test

# yarn v2
.yarn/cache
.yarn/unplugged
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*

Using this command with the name of your preferred programming language can download typical settings required for that language.

## The language name passed in should follow the naming convention listed in the file name available 
## https://github.com/github/gitignore
curl -o .gitignore  https://raw.githubusercontent.com/github/gitignore/master/<Programming Language here>.gitignore

How to add your own entries to Git ignore

On occasion you may want to add additional rules to your git ignore file and this is very easy to do so and there are just a few things you need to know regarding the syntax used in git ignore files

The entries in this file can also follow a matching pattern.

  • * is used as a wildcard match
  • / is used to ignore path names relative to the .gitignore file
  • # is used to add comments to a .gitignore file

Some typical examples of implementing rules may be:

# Ignore the node_modules folder in the project directory
node_modules

## Ignore all named local environment variable files   i.e.  .env.local etc
.env.**.local

## Ignore all files in the .cache folder

.cache/

## ignore all files in the temp folder in src folder with a .tmp extension but include others

src/temp/**.tmp

Which types of file should be ignored?

Typically, you should never track automatically generated files, i.e. files generated by the build system of a project. The reason for this is there is a high chance they will get out of sync with their source, they are not necessary and are always re-generated anyway.

Temporary files and by-products specific to a user's tool chain, should also not be included as tracked files.

Conclusion

Using a .gitignore files enables you to control which files and file types can be not allowed to be stored in your Git repository.

Typically, you may not want to include all the files in your local copy of a project in your commits. For instance, you may want to exclude, compiled libraries, system logs or configuration files containing sensitive data. To ignore files, you can specify which ones you want to ignore in .gitignore.

A project can contain multiple .gitignore files. You can override a .gitignore rule using the -f flag when you use the git add command.