It’s not always the case that you want to include every file in a folder inside a Git repository.
When you’re working with a local version of a repository, you may have files that you want to be kept separate. These may contain configurations or local variables that are private and should not be seen by other collaborators.
That’s where the .gitignore file comes in. This file allows you to instruct Git to ignore files.
In this guide, we’re going to talk about what .gitignore is, how it works, and how you can write your own .gitignore file. Without further ado, let’s get started!
What is .gitignore?
.gitignore is a text file that is usually placed within the root directory of a Git repository. This file tells Git which files or folders to ignore within a project.
By default, Git tracks all the files in a repository when you add them to a commit. This means that every file, including configuration files and compiled code, will be added to a commit if you use the * operator. This operator is used to stage all files into a commit.
The .gitignore file allows you to state which files should be ignored.
Often, developers want to ignore output folders, hidden system files, and compiled code. For instance, if you have a .env file in a repository, you may want to hide it. This is because .env files usually contain API keys which you may not want to commit to a repository.
There is no ignore command you can use to ignore files. You need to make a list of all the files that you want to ignore in the .gitignore file.
How to Write a .gitignore File
.gitignore file is simple. Open up a command shell and create a text file called
.gitignore in the root directory of a project. You can do this using the touch command:
Our .gitignore file is now created. We do not need to set it up with any configuration settings; all we need to do is add the files we want to ignore.
Consider the following
This file ignores two resources: all files in the node_modules directory and the .env file.
Let’s say that we want to ignore multiple files or directories. We can do this by using the * wildcard.
Let’s ignore all .pyc files in a repository:
This rule will instruct Git to ignore any file whose name ends in .pyc.
GitHub has created an excellent collection of gitignore files that you can use on their site. View GitHub’s collection of gitignore files.
Using Multiple .gitignore Files
You can use multiple .gitignore files in the same repository. This works because .gitignore is relative to the directory in which it is placed.
In our last example, we placed .gitignore in the root directory of our project. Let’s say that we want to ignore all the files that end in .pyc in the diff/ folder. We could do this by creating a file called .gitignore in the diff folder:
We would add the following rule to the .gitignore file:
When we go to commit code to our repository, Git will ignore any file in the diff/ folder which ends in .pyc.
This setup is best when you only need rules to apply to certain folders within a project. However, it can be confusing to have multiple .gitignore files in one project. An alternative would be to be more specific when you state which files your project should ignore and keep all your rules in one .gitignore file. Consider this file:
This .gitignore was placed in the root directory of a Git project. It instructs Git to ignore all files ending in .txt in the project. It also instructs Git to ignore all files ending in .pyc which are in the diff/ folder.
How to Create a Global Git Ignore Rule
It can be time consuming to define a .gitignore file for every project you create. What’s more, you’ll usually find that most of your projects use the same set of .gitignore rules.
You can set a global git ignore rule which will automatically set the gitignore rules for every repository on your system. This file is usually placed in your home directory of your operating system, such as
Let’s create a global .gitignore file:
This command creates an empty .gitignore file in our home directory. Open up this file and add in whatever rules you want to set for all the Git repositories on your system.
Once you have configured your gitignore file, you can enforce its rules using the
git config --global core.excludesFile ~/.gitignore
This command sets the rules in the
~/.gitignore file to apply to all Git repositories on a computer.
Be careful when you are defining a global git ignore rule. This is because the rules in a global .gitignore will be set by default and you may not want them to apply to all your projects.
A global .gitignore file is best used for common files like .env which you will almost never want to commit to a git repository.
How to Ignore a Committed File
You cannot always anticipate which files you will want to ignore in a project. It may be the case that you have previously committed a file to a repository but now you want to ignore it.
Let’s ignore the file
config.json which has been committed to our repository. We should start by adding an ignore rule to our
echo config.json >> .gitignore
This command appends
config.json to the end of our .gitignore file. Now we have to remove the file from our repository. We can do this using the git rm –cached command. This command will only remove a file from your repository. It will remain a local file on your computer.
git rm --cached config.json
Next time we create a commit, the config.json file will be ignored.
How to Commit an Ignored File
You can commit a file that has been ignored in your .gitignore file.
This may be useful if you are creating default config files that you want to commit to a repository that would otherwise be ignored. You can commit an ignored file using the -f flag when you are adding a file to the staging area:
git add -f config.json
git commit -m “feat: Create default config file”
This code adds the file config.json to the staging area. It then creates a commit based on the contents of the staging area. You can learn more about the git add in our git add tutorial. You can read about the git commit command in our git commit tutorial.
How to Debug a .gitignore File
You can have multiple
.gitignore files in a project, as we mentioned earlier. This means that you may run into a situation where you notice a file is being ignored that should not be. The more configuration files you have, the more places there are where ignore rules may be set.
To find out what rule is causing a file to be ignored, you can use the check-ignore function:
git check-ignore config.json
This command will tell you the name of the file containing the rule that ignores a file, the line number on which that rule is set, as well as the rule itself:
This tells us that we have ignored the file
config.json on line 1 of our .gitignore file. This
.gitignore file is stored in the root directory for our project because it has no directory specified.
The .gitignore file allows you to ignore files in a Git repository.
You may not want to include all the files in your local copy of a project in your commits. For instance, you may not want to commit compiled code, or system logs, or config files. 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.
Now you’re ready to use the .gitignore file like an expert!