-----------
A `gitignore` file specifies intentionally untracked files that
-git should ignore. Each line in a `gitignore` file specifies a
-pattern.
+Git should ignore.
+Files already tracked by Git are not affected; see the NOTES
+below for details.
-When deciding whether to ignore a path, git normally checks
+Each line in a `gitignore` file specifies a pattern.
+When deciding whether to ignore a path, Git normally checks
`gitignore` 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):
* Patterns read from a `.gitignore` file in the same directory
as the path, or in any parent directory, with patterns in the
- higher level files (up to the root) being overriden by those in
- lower level files down to the directory containing the file.
+ higher level files (up to the toplevel of the work tree) being overridden
+ by those in lower level files down to the directory containing the file.
These patterns match relative to the location of the
`.gitignore` file. A project normally includes such
`.gitignore` files in its repository, containing patterns for
* Patterns read from the file specified by the configuration
variable 'core.excludesfile'.
-The underlying git plumbing tools, such as
-gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read
+Which file to place a pattern in depends on how the pattern is meant to
+be used.
+
+ * 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 `.gitignore` file.
+
+ * 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's workflow) should go into
+ the `$GIT_DIR/info/exclude` file.
+
+ * Patterns which a user wants Git to
+ ignore in all situations (e.g., backup or temporary files generated by
+ the user's editor of choice) generally go into a file specified by
+ `core.excludesfile` in the user's `~/.gitconfig`. 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.
+
+The underlying Git plumbing tools, such as
+'git ls-files' and 'git read-tree', read
`gitignore` patterns specified by command-line options, or from
-files specified by command-line options. Higher-level git
-tools, such as gitlink:git-status[1] and gitlink:git-add[1],
+files specified by command-line options. Higher-level Git
+tools, such as 'git status' and 'git add',
use patterns from the sources specified above.
-Patterns have the following format:
+PATTERN FORMAT
+--------------
- A blank line matches no files, so it can serve as a separator
for readability.
- A line starting with # serves as a comment.
+ Put a backslash ("`\`") in front of the first hash for patterns
+ that begin with a hash.
- - An optional prefix '!' which negates the pattern; any
+ - An optional prefix "`!`" which negates the pattern; any
matching file excluded by a previous pattern will become
included again. If a negated pattern matches, this will
override lower precedence patterns sources.
+ Put a backslash ("`\`") in front of the first "`!`" for patterns
+ that begin with a literal "`!`", for example, "`\!important!.txt`".
+
+ - If the pattern ends with a slash, it is removed for the
+ purpose of the following description, but it would only find
+ a match with a directory. In other words, `foo/` will match a
+ directory `foo` and paths underneath it, but will not match a
+ regular file or a symbolic link `foo` (this is consistent
+ with the way how pathspec works in general in Git).
- - If the pattern does not contain a slash '/', git treats it as
+ - If the pattern does not contain a slash '/', Git treats it as
a shell glob pattern and checks for a match against the
- pathname without leading directories.
+ pathname relative to the location of the `.gitignore` file
+ (relative to the toplevel of the work tree if not from a
+ `.gitignore` file).
- - Otherwise, git treats the pattern as a shell glob suitable
+ - Otherwise, Git treats the pattern as a shell glob suitable
for consumption by fnmatch(3) with the FNM_PATHNAME flag:
wildcards in the pattern will not match a / in the pathname.
- For example, "Documentation/\*.html" matches
- "Documentation/git.html" but not
- "Documentation/ppc/ppc.html". A leading slash matches the
- beginning of the pathname; for example, "/*.c" matches
- "cat-file.c" but not "mozilla-sha1/sha1.c".
+ For example, "Documentation/{asterisk}.html" matches
+ "Documentation/git.html" but not "Documentation/ppc/ppc.html"
+ or "tools/perf/Documentation/perf.html".
+
+ - A leading slash matches the beginning of the pathname.
+ For example, "/{asterisk}.c" matches "cat-file.c" but not
+ "mozilla-sha1/sha1.c".
+
+Two consecutive asterisks ("`**`") in patterns matched against
+full pathname may have special meaning:
+
+ - A leading "`**`" followed by a slash means match in all
+ directories. For example, "`**/foo`" matches file or directory
+ "`foo`" anywhere, the same as pattern "`foo`". "**/foo/bar"
+ matches file or directory "`bar`" anywhere that is directly
+ under directory "`foo`".
+
+ - A trailing "/**" matches everything inside. For example,
+ "abc/**" matches all files inside directory "abc", relative
+ to the location of the `.gitignore` file, with infinite depth.
-An example:
+ - A slash followed by two consecutive asterisks then a slash
+ matches zero or more directories. For example, "`a/**/b`"
+ matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
+
+ - Other consecutive asterisks are considered invalid.
+
+NOTES
+-----
+
+The purpose of gitignore files is to ensure that certain files
+not tracked by Git remain untracked.
+
+To ignore uncommitted changes in a file that is already tracked,
+use 'git update-index {litdd}assume-unchanged'.
+
+To stop tracking a file that is currently tracked, use
+'git rm --cached'.
+
+EXAMPLES
+--------
--------------------------------------------------------------
- $ git-status
+ $ git status
[...]
# Untracked files:
[...]
*.html
# except foo.html which is maintained by hand
!foo.html
- $ git-status
+ $ git status
[...]
# Untracked files:
[...]
$ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
--------------------------------------------------------------
-The second .gitignore prevents git from ignoring
+The second .gitignore prevents Git from ignoring
`arch/foo/kernel/vmlinux.lds.S`.
-Documentation
--------------
-Documentation by David Greaves, Junio C Hamano, Josh Triplett,
-Frank Lichtenheld, and the git-list <git@vger.kernel.org>.
+SEE ALSO
+--------
+linkgit:git-rm[1],
+linkgit:git-update-index[1],
+linkgit:gitrepository-layout[5],
+linkgit:git-check-ignore[1]
GIT
---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[1] suite