gitignore.5 (12113B)
- '\" t
- .\" Title: gitignore
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GITIGNORE" "5" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
- .\" -----------------------------------------------------------------
- .\" * Define some portability stuff
- .\" -----------------------------------------------------------------
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .\" http://bugs.debian.org/507673
- .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .ie \n(.g .ds Aq \(aq
- .el .ds Aq '
- .\" -----------------------------------------------------------------
- .\" * set default formatting
- .\" -----------------------------------------------------------------
- .\" disable hyphenation
- .nh
- .\" disable justification (adjust text to left margin only)
- .ad l
- .\" -----------------------------------------------------------------
- .\" * MAIN CONTENT STARTS HERE *
- .\" -----------------------------------------------------------------
- .SH "NAME"
- gitignore \- Specifies intentionally untracked files to ignore
- .SH "SYNOPSIS"
- .sp
- $XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, \&.gitignore
- .SH "DESCRIPTION"
- .sp
- A \fBgitignore\fR file specifies intentionally untracked files that Git should ignore\&. Files already tracked by Git are not affected; see the NOTES below for details\&.
- .sp
- Each line in a \fBgitignore\fR file specifies a pattern\&. When deciding whether to ignore a path, Git normally checks \fBgitignore\fR patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of precedence, the last matching pattern decides the outcome):
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Patterns read from the command line for those commands that support them\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Patterns read from a \&.\fBgitignore\fR
- file in the same directory as the path, or in any parent directory (up to the top\-level of the working tree), with patterns in the higher level files being overridden by those in lower level files down to the directory containing the file\&. These patterns match relative to the location of the \&.\fBgitignore\fR
- file\&. A project normally includes such \&.\fBgitignore\fR
- files in its repository, containing patterns for files generated as part of the project build\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Patterns read from
- \fB$GIT_DIR/info/exclude\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Patterns read from the file specified by the configuration variable
- \fBcore\&.excludesFile\fR\&.
- .RE
- .sp
- Which file to place a pattern in depends on how the pattern is meant to be used\&.
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Patterns which should be version\-controlled and distributed to other repositories via clone (i\&.e\&., files that all developers will want to ignore) should go into a \&.\fBgitignore\fR
- file\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Patterns which are specific to a particular repository but which do not need to be shared with other related repositories (e\&.g\&., auxiliary files that live inside the repository but are specific to one user\(cqs workflow) should go into the
- \fB$GIT_DIR/info/exclude\fR
- file\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Patterns which a user wants Git to ignore in all situations (e\&.g\&., backup or temporary files generated by the user\(cqs editor of choice) generally go into a file specified by
- \fBcore\&.excludesFile\fR
- in the user\(cqs
- \fB~/\&.gitconfig\fR\&. Its default value is $XDG_CONFIG_HOME/git/ignore\&. If $XDG_CONFIG_HOME is either not set or empty, $HOME/\&.config/git/ignore is used instead\&.
- .RE
- .sp
- The underlying Git plumbing tools, such as \fIgit ls\-files\fR and \fIgit read\-tree\fR, read \fBgitignore\fR patterns specified by command\-line options, or from files specified by command\-line options\&. Higher\-level Git tools, such as \fIgit status\fR and \fIgit add\fR, use patterns from the sources specified above\&.
- .SH "PATTERN FORMAT"
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- A blank line matches no files, so it can serve as a separator for readability\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- A line starting with # serves as a comment\&. Put a backslash ("\e") in front of the first hash for patterns that begin with a hash\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Trailing spaces are ignored unless they are quoted with backslash ("\e")\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- An optional prefix "!" which negates the pattern; any matching file excluded by a previous pattern will become included again\&. It is not possible to re\-include a file if a parent directory of that file is excluded\&. Git doesn\(cqt list excluded directories for performance reasons, so any patterns on contained files have no effect, no matter where they are defined\&. Put a backslash ("\e") in front of the first "!" for patterns that begin with a literal "!", for example, "\e!important!\&.\fBtxt\fR"\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The slash "\fB/\fR" is used as the directory separator\&. Separators may occur at the beginning, middle or end of the \&.\fBgitignore\fR
- search pattern\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- If there is a separator at the beginning or middle (or both) of the pattern, then the pattern is relative to the directory level of the particular \&.\fBgitignore\fR
- file itself\&. Otherwise the pattern may also match at any level below the \&.\fBgitignore\fR
- level\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- If there is a separator at the end of the pattern then the pattern will only match directories, otherwise the pattern can match both files and directories\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- For example, a pattern
- \fBdoc/frotz/\fR
- matches
- \fBdoc/frotz\fR
- directory, but not
- \fBa/doc/frotz\fR
- directory; however
- \fBfrotz/\fR
- matches
- \fBfrotz\fR
- and
- \fBa/frotz\fR
- that is a directory (all paths are relative from the \&.\fBgitignore\fR
- file)\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- An asterisk "*" matches anything except a slash\&. The character "?" matches any one character except "\fB/\fR"\&. The range notation, e\&.g\&. [\fBa\-zA\-Z\fR], can be used to match one of the characters in a range\&. See fnmatch(3) and the FNM_PATHNAME flag for a more detailed description\&.
- .RE
- .sp
- Two consecutive asterisks ("**") in patterns matched against full pathname may have special meaning:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- A leading "**" followed by a slash means match in all directories\&. For example, "**/foo" matches file or directory "\fBfoo\fR" anywhere, the same as pattern "\fBfoo\fR"\&. "**/foo/bar" matches file or directory "\fBbar\fR" anywhere that is directly under directory "\fBfoo\fR"\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- A trailing "\fB/\fR**" matches everything inside\&. For example, "\fBabc/\fR**" matches all files inside directory "\fBabc\fR", relative to the location of the \&.\fBgitignore\fR
- file, with infinite depth\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- A slash followed by two consecutive asterisks then a slash matches zero or more directories\&. For example, "\fBa/\fR**/b" matches "\fBa/b\fR", "\fBa/x/b\fR", "\fBa/x/y/b\fR" and so on\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Other consecutive asterisks are considered regular asterisks and will match according to the previous rules\&.
- .RE
- .SH "CONFIGURATION"
- .sp
- The optional configuration variable \fBcore\&.excludesFile\fR indicates a path to a file containing patterns of file names to exclude, similar to \fB$GIT_DIR/info/exclude\fR\&. Patterns in the exclude file are used in addition to those in \fB$GIT_DIR/info/exclude\fR\&.
- .SH "NOTES"
- .sp
- The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked\&.
- .sp
- To stop tracking a file that is currently tracked, use \fIgit rm \-\-cached\fR to remove the file from the index\&. The filename can then be added to the \&.\fBgitignore\fR file to stop the file from being reintroduced in later commits\&.
- .sp
- Git does not follow symbolic links when accessing a \&.\fBgitignore\fR file in the working tree\&. This keeps behavior consistent when the file is accessed from the index or a tree versus from the filesystem\&.
- .SH "EXAMPLES"
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The pattern
- \fBhello\&.\fR* matches any file or directory whose name begins with
- \fBhello\&.\fR\&. If one wants to restrict this only to the directory and not in its subdirectories, one can prepend the pattern with a slash, i\&.e\&.
- \fB/hello\&.\fR*; the pattern now matches
- \fBhello\&.txt\fR,
- \fBhello\&.c\fR
- but not
- \fBa/hello\&.java\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The pattern
- \fBfoo/\fR
- will match a directory
- \fBfoo\fR
- and paths underneath it, but will not match a regular file or a symbolic link
- \fBfoo\fR
- (this is consistent with the way how pathspec works in general in Git)
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The pattern
- \fBdoc/frotz\fR
- and
- \fB/doc/frotz\fR
- have the same effect in any \&.\fBgitignore\fR
- file\&. In other words, a leading slash is not relevant if there is already a middle slash in the pattern\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The pattern
- \fBfoo/\fR*, matches
- \fBfoo/test\&.json\fR
- (a regular file),
- \fBfoo/bar\fR
- (a directory), but it does not match
- \fBfoo/bar/hello\&.c\fR
- (a regular file), as the asterisk in the pattern does not match
- \fBbar/hello\&.c\fR
- which has a slash in it\&.
- .RE
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git status
- [\&.\&.\&.]
- # Untracked files:
- [\&.\&.\&.]
- # Documentation/foo\&.html
- # Documentation/gitignore\&.html
- # file\&.o
- # lib\&.a
- # src/internal\&.o
- [\&.\&.\&.]
- $ cat \&.git/info/exclude
- # ignore objects and archives, anywhere in the tree\&.
- *\&.[oa]
- $ cat Documentation/\&.gitignore
- # ignore generated html files,
- *\&.html
- # except foo\&.html which is maintained by hand
- !foo\&.html
- $ git status
- [\&.\&.\&.]
- # Untracked files:
- [\&.\&.\&.]
- # Documentation/foo\&.html
- [\&.\&.\&.]
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- Another example:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ cat \&.gitignore
- vmlinux*
- $ ls arch/foo/kernel/vm*
- arch/foo/kernel/vmlinux\&.lds\&.S
- $ echo \*(Aq!/vmlinux*\*(Aq >arch/foo/kernel/\&.gitignore
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- The second \&.gitignore prevents Git from ignoring \fBarch/foo/kernel/vmlinux\&.lds\&.S\fR\&.
- .sp
- Example to exclude everything except a specific directory \fBfoo/bar\fR (note the \fB/\fR* \- without the slash, the wildcard would also exclude everything within \fBfoo/bar\fR):
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ cat \&.gitignore
- # exclude everything except directory foo/bar
- /*
- !/foo
- /foo/*
- !/foo/bar
- .fi
- .if n \{\
- .RE
- .\}
- .SH "SEE ALSO"
- .sp
- \fBgit-rm\fR(1), \fBgitrepository-layout\fR(5), \fBgit-check-ignore\fR(1)
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite