path: root/man5/gitignore.5

'\" 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: 2024-04-15
.\"    Manual: Git Manual
.\"    Source: Git 2.44.0.616.g548fe35913
.\"  Language: English
.\"
.TH "GITIGNORE" "5" "2024\-04\-15" "Git 2\&.44\&.0\&.616\&.g548fe3" "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 "\fB/\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 to remove the file from the index\&. The filename can then be added to the \fB\&.gitignore\fR file to stop the file from being reintroduced in later commits\&.
.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
\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
.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