Having a well structured .gitignore file is something that is often taken for granted. However, it is an important part of maintaining productivity with git. Without a .gitignore, maintaining files in git can become tedious and confusing.
It allows you to easily ignore files that are not important to check into git so that you are able to focus on your changes without distraction.
Although, your .gitignore file will not be one that you modify often, keeping it clean and well structured makes it easy to maintain a clean repository with minimal effort.
This guide focuses mostly on the basic structure and patterns of a .gitignore file but also discusses how to create a .gitignore for new or existing React repositories.
#are comments and are also ignored.
The simplest way to ignore a file is to explicitly specify it by name.
For example, the line
file.txt would ignore the file
In .gitignore files, forward-slash (
/) is always used as the path separator. Directories can be ignored with or without a trailing path separator, but the two mean different things. A line ending with a path separator will only match directories while a line without it will match files or directories. For example,
bin/ will match all directories called bin.
bin will match all files or directories called bin. Ignoring a directory also ignores all files and subdirectories in that directory.
By default specifying a pattern to ignore will recursively ignore all instances of that pattern. For example, if you ignore
file in the following directory structure, it will ignore
1myproject 2|-- .gitignore 3|-- file 4|-- subdir1 5| `-- file 6`-- subdir2 7 `-- subdir2-1 8 `-- file
Prefixing a pattern with a path separator allows you to specify an absolute path starting from the .gitignore file. So, in the previous example, if you wanted to ignore just
/myproject/file, the pattern in the .gitignore file would need to be
/file. Ignoring just
myproject/subdir1/file would require
.gitignore also allows wildcards and ranges. An asterisk
* is the most common wildcard character. It matches zero or more characters that are not a slash. For example, the following could be used to ignore all
.json files and all
.yml files that have
-local. in the name:
Range notation is a way to specify groups of characters allowable characters to match a single character. This notation is used by creating a list of characters contained in brackets
. For example
[abcdefghi] would match any character
An easier way to specify ranges that are sequential is to use a
[a-i] would match any character
i and is identical to
[abcdefghi] but shorter to type and easier to read.
Dashes can be used multiple times to specify multiple groupings. For example
[a-zA-Z] is a common way to specify that a character can match any letter from
z either capital or lowercase.
! in front of the pattern will cause git to explicitly not ignore that file or directory. This can be useful to ignore all files and directories matching a pattern except for some specific ones. For example, in order to ignore all configuration files except for one that is a sample, you could do the following:
This would ignore all
.config files except for /appname/settings.sample.config.
If you have multiple sample
.config files in my repository, you do the following:
NOTE: It is not possible use a
!to cancel ignoring anything inside of an ignored directory. Once a directory is ignored, git will no longer transverse into that directory at all.
This is not a comprehensive list of all the patterns that .gitignore can handle. For more patterns refer to the official git documentation on .gitignore.
A .gitignore file is something that is often created and forgotten. However, in the lifetime of a project it is not uncommon to need to return to a .gitignore when it comes time to refactor a project. When that time comes it is great to have a well organized .gitignore.
The most common approach to organize a .gitignore is to split patterns into groups separated by blank lines and using comments as group headers. My .gitignore files often look something like the following:
1# binaries 2bin/ 3dist/ 4lib/ 5 6# editors 7*.swp 8.idea/ 9.vs/ 10.vscode/ 11.DS_Store
Once you have the basics down, all that is left is applying it to a specific language or framework.
Good files to ignore are consistently generated. This includes compiled artifacts or files created by downloading dependencies. It can also include configuration files generated by your IDE or text editor, such as the
.idea folder for Jetbrains products or the
.vs folder from Visual Studio.
Note: Some editor configuration files can be included in git. As a rule of thumb if all contributors to a project use the same editor I will include the configuration files. Otherwise, I generally ignore them by using .gitignore
For React projects, common files or directories to ignore include:
In all honesty, the easiest and potentially the most common way to start a .gitignore file is to generate it from a trusted source. There are several ways to do this. Some may already be built into your "new project workflow."
I generally generate my initial .gitignore at the same time as creating a new git repository using Github. This can be done from the Create New Repository page by clicking on the "Add .gitignore:" dropdown at the bottom of the page and select your language of choice.
If you have an existing project, Github's .gitignore templates can be found here.
If you use a tool for generating new projects such as Create React App, a .gitignore will often be generated along with the new application.
After generating a .gitignore, it is good practice to review it. Generated .gitignore files are generic - that means, they may be cluttered with lines that do not apply to your project or they could be missing cases that are important to you. Go ahead and modify or reorganize it to match your needs.
Certainly, this is not all that can be done with a .gitignore. More complex .gitignore patterns can be found in the official documentation. However, you should now be able to create one and tailor it to your project. Remember, starting with a clean .gitignore file will help you keep a clean repository full of clean code.