| '\" t |
| .\" Title: gitignore |
| .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
| .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> |
| .\" Date: 03/07/2022 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.35.1.415.gc2162907e9 |
| .\" Language: English |
| .\" |
| .TH "GITIGNORE" "5" "03/07/2022" "Git 2\&.35\&.1\&.415\&.gc21629" "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 |
| \fB\&.gitignore\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 |
| \fB\&.gitignore\fR |
| file\&. A project normally includes such |
| \fB\&.gitignore\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 |
| \fB\&.gitignore\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 ("\fB\e\fR") 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 ("\fB\e\fR")\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| An optional prefix "\fB!\fR" 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 ("\fB\e\fR") in front of the first "\fB!\fR" for patterns that begin with a literal "\fB!\fR", for example, "\fB\e!important!\&.txt\fR"\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| The slash |
| \fI/\fR |
| is used as the directory separator\&. Separators may occur at the beginning, middle or end of the |
| \fB\&.gitignore\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 |
| \fB\&.gitignore\fR |
| file itself\&. Otherwise the pattern may also match at any level below the |
| \fB\&.gitignore\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 |
| \fB\&.gitignore\fR |
| file)\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| An asterisk "\fB*\fR" matches anything except a slash\&. The character "\fB?\fR" matches any one character except "\fB/\fR"\&. The range notation, e\&.g\&. |
| \fB[a\-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 ("\fB**\fR") 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 "\fB**\fR" followed by a slash means match in all directories\&. For example, "\fB**/foo\fR" matches file or directory "\fBfoo\fR" anywhere, the same as pattern "\fBfoo\fR"\&. "\fB**/foo/bar\fR" 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 |
| \fB\&.gitignore\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/**/b\fR" 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\&. |
| .sp |
| Git does not follow symbolic links when accessing a \fB\&.gitignore\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 |
| \fB\&.gitignore\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 "foo/*", matches "foo/test\&.json" (a regular file), "foo/bar" (a directory), but it does not match "foo/bar/hello\&.c" (a regular file), as the asterisk in the pattern does not match "bar/hello\&.c" 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 |
| .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 |
| .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 |
| .\} |
| .sp |
| .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 |