Ignoring Files and Directories in Git (.gitignore)
6 min read
Often, when working on a project that uses Git, you’ll want to exclude specific files or directories from being pushed to the remote repository.
.gitignore file specifies what untracked files Git should ignore.
What Files Should be Ignored?
Ignored files are usually platform-specific files or automatically created files from the build systems. Some common examples include:
- Runtime files such as log, lock, cache, or temporary files.
- Files with sensitive information, such as passwords or API keys.
- Compiled code, such as
- Dependency directories, such as
- Build directories, such as
- System files like
- IDE or text editor configuration files.
.gitignore file is a plain text file in which each line contains a pattern for files or directories to ignore.
.gitignore uses globbing patterns to match filenames with wildcard characters. If you have files or directories containing a wildcard pattern, you can use a single backslash (
\) to escape the character.
Lines starting with a hash mark (
#) are comments and are ignored. Empty lines can be used to improve the readability of the file and to group related lines of patterns.
The slash symbol (
/) represents a directory separator. The slash at the beginning of a pattern is relative to the directory where the
If the pattern starts with a slash, it matches files and directories only in the repository root.
If the pattern doesn’t start with a slash, it matches files and directories in any directory or subdirectory.
If the pattern ends with a slash, it matches only directories. When a directory is ignored, all of its files and subdirectories are also ignored.
Literal File Names
The most straightforward pattern is a literal file name without any special characters.
* - The asterisk symbol matches zero or more characters.
** - Two adjacent asterisk symbols match any file or zero or more directories. When followed by a slash (
/), it matches only directories.
|Matches anything inside the |
? - The question mark matches any single character.
[...] - Matches any of the characters enclosed in the square brackets. When two characters are separated by a hyphen
- it denotes a range of characters. The range includes all characters that are between those two characters. The ranges can be alphabetic or numeric.
If the first character following the
[ is an exclamation mark (
!), then the pattern matches any character except those from the specified set.
A pattern that starts with an exclamation mark (
!) negates (re-include) any file that is ignored by the previous pattern. The exception to this rule is to re-include a file if its parent directory is excluded.
Below is an example of what your
.gitignore file could look like:
# Ignore the node_modules directory node_modules/ # Ignore Logs logs *.log # Ignore the build directory /dist # The file containing environment variables .env # Ignore IDE specific files .idea/ .vscode/ *.sw*
.gitignore file is usually placed in the repository’s root directory. However you can create multiple
.gitignore files in different subdirectories in your repository. The patterns in the
.gitignore files are matched relative to the directory where the file resides.
Patterns defined in the files that reside in lower-level directories (sub-directories) have precedence over those in higher-level directories.
.gitignore files are shared with other developers and should contain patterns that are useful for all other users of the repository.
Personal Ignore Rules
Patterns that are specific to your local repository and should not be distributed to other repositories, should be set in the
For example, you can use this file to ignore generated files from your personal project tools.
Git also allows you to create a global
.gitignore file, where you can define ignore rules for every Git repository on your local system.
The file can be named anything you like and stored in any location. The most common place to keep this file is the home directory. You’ll have to manually create the file and configure Git to use it.
For example, to set
~/.gitignore_global as the global Git ignore file, you would do the following:
Create the file:
Add the file to the Git configuration:
git config --global core.excludesfile ~/.gitignore_global
Open the file with your text editor and add your rules to it.
Global rules are particularly useful for ignoring particular files that you never want to commit, such as files with sensitive information or compiled executables.
Ignoring a Previously Committed Files
The files in your working copy can be either tracked or untracked.
To ignore a file that has been previously committed, you’ll need to unstage and remove the file from the index, and then add a rule for the file in
git rm --cached filename
--cached option tells git not to delete the file from the working tree but only to remove it from the index.
To recursively remove a directory, use the
git rm --cached filename
If you want to remove the file from both the index and local filesystem, omit the
When recursively deleting files, use the
-n option that will perform a “dry run” and show you what files will be deleted:
git rm -r -n directory
Sometimes it can be challenging to determine why a specific file is being ignored, especially when you’re are using multiple
.gitignore files or complex patterns. This is where the
git check-ignore command with the
-v option, which tells git to display details about the matching pattern, comes handy.
For example, to check why the
www/yarn.lock file is ignored you would run:
git check-ignore -v www/yarn.lock
The output shows the path to the
gitignore file, the number of the matching line, and the actual pattern.
The command also accepts more than one filename as arguments, and the file doesn’t have to exist in your working tree.
Displaying All Ignored Files
git status command with the
--ignored option displays a list of all ignored files:
git status --ignored
.gitignore file allows you to exclude files from being checked into the repository. The file contains globbing patterns that describe which files and directories should be ignored.
gitignore.io is an online service that allows you to generate
.gitignore files for your operating system, programming language, or IDE.
If you have any questions or feedback, feel free to leave a comment.