2007-06-02 17:08:54 +00:00
|
|
|
gitignore(5)
|
|
|
|
============
|
|
|
|
|
|
|
|
NAME
|
|
|
|
----
|
|
|
|
gitignore - Specifies intentionally untracked files to ignore
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
--------
|
2018-06-27 04:46:51 +00:00
|
|
|
$XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, .gitignore
|
2007-06-02 17:08:54 +00:00
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
-----------
|
|
|
|
|
|
|
|
A `gitignore` file specifies intentionally untracked files that
|
2013-01-21 19:17:53 +00:00
|
|
|
Git should ignore.
|
|
|
|
Files already tracked by Git are not affected; see the NOTES
|
2010-11-10 19:00:48 +00:00
|
|
|
below for details.
|
2007-06-02 17:08:54 +00:00
|
|
|
|
2008-07-18 14:11:07 +00:00
|
|
|
Each line in a `gitignore` file specifies a pattern.
|
2013-01-21 19:17:53 +00:00
|
|
|
When deciding whether to ignore a path, Git normally checks
|
2007-06-02 17:08:54 +00:00
|
|
|
`gitignore` patterns from multiple sources, with the following
|
2007-07-21 23:53:49 +00:00
|
|
|
order of precedence, from highest to lowest (within one level of
|
|
|
|
precedence, the last matching pattern decides the outcome):
|
2007-06-02 17:08:54 +00:00
|
|
|
|
2007-07-21 23:53:49 +00:00
|
|
|
* Patterns read from the command line for those commands that support
|
|
|
|
them.
|
2007-06-02 17:08:54 +00:00
|
|
|
|
|
|
|
* Patterns read from a `.gitignore` file in the same directory
|
2007-07-21 23:53:49 +00:00
|
|
|
as the path, or in any parent directory, with patterns in the
|
2009-04-06 15:03:36 +00:00
|
|
|
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.
|
2007-06-02 17:08:54 +00:00
|
|
|
These patterns match relative to the location of the
|
|
|
|
`.gitignore` file. A project normally includes such
|
|
|
|
`.gitignore` files in its repository, containing patterns for
|
|
|
|
files generated as part of the project build.
|
|
|
|
|
2007-07-21 23:53:49 +00:00
|
|
|
* Patterns read from `$GIT_DIR/info/exclude`.
|
|
|
|
|
|
|
|
* Patterns read from the file specified by the configuration
|
2016-06-08 17:23:16 +00:00
|
|
|
variable `core.excludesFile`.
|
2007-07-21 23:53:49 +00:00
|
|
|
|
2008-03-27 05:31:00 +00:00
|
|
|
Which file to place a pattern in depends on how the pattern is meant to
|
2012-09-18 23:25:31 +00:00
|
|
|
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.
|
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
* Patterns which a user wants Git to
|
2012-09-18 23:25:31 +00:00
|
|
|
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
|
2015-03-11 20:32:45 +00:00
|
|
|
`core.excludesFile` in the user's `~/.gitconfig`. Its default value is
|
2012-09-18 23:25:31 +00:00
|
|
|
$XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or
|
|
|
|
empty, $HOME/.config/git/ignore is used instead.
|
2008-03-27 05:31:00 +00:00
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
The underlying Git plumbing tools, such as
|
2010-01-09 23:33:00 +00:00
|
|
|
'git ls-files' and 'git read-tree', read
|
2007-06-02 17:08:54 +00:00
|
|
|
`gitignore` patterns specified by command-line options, or from
|
2013-01-21 19:17:53 +00:00
|
|
|
files specified by command-line options. Higher-level Git
|
2010-01-09 23:33:00 +00:00
|
|
|
tools, such as 'git status' and 'git add',
|
2007-06-02 17:08:54 +00:00
|
|
|
use patterns from the sources specified above.
|
|
|
|
|
2010-11-10 18:57:39 +00:00
|
|
|
PATTERN FORMAT
|
|
|
|
--------------
|
2007-06-02 17:08:54 +00:00
|
|
|
|
|
|
|
- A blank line matches no files, so it can serve as a separator
|
|
|
|
for readability.
|
|
|
|
|
|
|
|
- A line starting with # serves as a comment.
|
2012-10-07 03:13:54 +00:00
|
|
|
Put a backslash ("`\`") in front of the first hash for patterns
|
|
|
|
that begin with a hash.
|
2007-06-02 17:08:54 +00:00
|
|
|
|
2014-11-04 22:18:33 +00:00
|
|
|
- Trailing spaces are ignored unless they are quoted with backslash
|
2014-02-09 00:26:38 +00:00
|
|
|
("`\`").
|
|
|
|
|
2012-10-07 03:13:54 +00:00
|
|
|
- An optional prefix "`!`" which negates the pattern; any
|
2007-06-02 17:08:54 +00:00
|
|
|
matching file excluded by a previous pattern will become
|
2016-03-18 18:06:15 +00:00
|
|
|
included again. It is not possible to re-include a file if a parent
|
|
|
|
directory of that file is excluded. Git doesn't list excluded
|
|
|
|
directories for performance reasons, so any patterns on contained
|
|
|
|
files have no effect, no matter where they are defined.
|
2012-10-07 03:13:54 +00:00
|
|
|
Put a backslash ("`\`") in front of the first "`!`" for patterns
|
|
|
|
that begin with a literal "`!`", for example, "`\!important!.txt`".
|
2007-06-02 17:08:54 +00:00
|
|
|
|
2008-01-31 09:17:48 +00:00
|
|
|
- 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
|
2013-01-21 19:17:53 +00:00
|
|
|
with the way how pathspec works in general in Git).
|
2008-01-31 09:17:48 +00:00
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
- If the pattern does not contain a slash '/', Git treats it as
|
2007-06-02 17:08:54 +00:00
|
|
|
a shell glob pattern and checks for a match against the
|
2010-03-05 15:56:39 +00:00
|
|
|
pathname relative to the location of the `.gitignore` file
|
|
|
|
(relative to the toplevel of the work tree if not from a
|
|
|
|
`.gitignore` file).
|
2007-06-02 17:08:54 +00:00
|
|
|
|
2018-02-01 09:59:15 +00:00
|
|
|
- Otherwise, Git treats the pattern as a shell glob: "`*`" matches
|
|
|
|
anything except "`/`", "`?`" matches any one character except "`/`"
|
|
|
|
and "`[]`" matches one character in a selected range. See
|
|
|
|
fnmatch(3) and the FNM_PATHNAME flag for a more detailed
|
|
|
|
description.
|
2010-03-05 15:56:39 +00:00
|
|
|
|
|
|
|
- A leading slash matches the beginning of the pathname.
|
2010-08-20 10:30:56 +00:00
|
|
|
For example, "/{asterisk}.c" matches "cat-file.c" but not
|
2010-03-05 15:56:39 +00:00
|
|
|
"mozilla-sha1/sha1.c".
|
2007-06-02 17:08:54 +00:00
|
|
|
|
2012-10-15 06:26:02 +00:00
|
|
|
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
|
2013-11-07 16:30:47 +00:00
|
|
|
"`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`"
|
2012-10-15 06:26:02 +00:00
|
|
|
matches file or directory "`bar`" anywhere that is directly
|
|
|
|
under directory "`foo`".
|
|
|
|
|
2013-11-07 16:30:47 +00:00
|
|
|
- A trailing "`/**`" matches everything inside. For example,
|
|
|
|
"`abc/**`" matches all files inside directory "`abc`", relative
|
2012-10-15 06:26:02 +00:00
|
|
|
to the location of the `.gitignore` file, with infinite depth.
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
2018-10-27 08:48:23 +00:00
|
|
|
- Other consecutive asterisks are considered regular asterisks and
|
|
|
|
will match according to the previous rules.
|
2012-10-15 06:26:02 +00:00
|
|
|
|
2010-11-10 19:00:48 +00:00
|
|
|
NOTES
|
|
|
|
-----
|
|
|
|
|
|
|
|
The purpose of gitignore files is to ensure that certain files
|
2013-01-21 19:17:53 +00:00
|
|
|
not tracked by Git remain untracked.
|
2010-11-10 19:00:48 +00:00
|
|
|
|
|
|
|
To stop tracking a file that is currently tracked, use
|
|
|
|
'git rm --cached'.
|
|
|
|
|
2010-11-10 18:57:39 +00:00
|
|
|
EXAMPLES
|
|
|
|
--------
|
2007-06-02 17:08:54 +00:00
|
|
|
|
|
|
|
--------------------------------------------------------------
|
2008-06-30 06:09:04 +00:00
|
|
|
$ git status
|
2007-06-02 17:08:54 +00:00
|
|
|
[...]
|
|
|
|
# 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
|
2008-06-30 06:09:04 +00:00
|
|
|
$ git status
|
2007-06-02 17:08:54 +00:00
|
|
|
[...]
|
|
|
|
# Untracked files:
|
|
|
|
[...]
|
|
|
|
# Documentation/foo.html
|
|
|
|
[...]
|
|
|
|
--------------------------------------------------------------
|
|
|
|
|
|
|
|
Another example:
|
|
|
|
|
|
|
|
--------------------------------------------------------------
|
|
|
|
$ cat .gitignore
|
|
|
|
vmlinux*
|
|
|
|
$ ls arch/foo/kernel/vm*
|
|
|
|
arch/foo/kernel/vmlinux.lds.S
|
|
|
|
$ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
|
|
|
|
--------------------------------------------------------------
|
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
The second .gitignore prevents Git from ignoring
|
2007-06-02 17:08:54 +00:00
|
|
|
`arch/foo/kernel/vmlinux.lds.S`.
|
|
|
|
|
2013-11-07 21:36:29 +00:00
|
|
|
Example to exclude everything except a specific directory `foo/bar`
|
|
|
|
(note the `/*` - without the slash, the wildcard would also exclude
|
|
|
|
everything within `foo/bar`):
|
|
|
|
|
|
|
|
--------------------------------------------------------------
|
|
|
|
$ cat .gitignore
|
|
|
|
# exclude everything except directory foo/bar
|
|
|
|
/*
|
|
|
|
!/foo
|
|
|
|
/foo/*
|
|
|
|
!/foo/bar
|
|
|
|
--------------------------------------------------------------
|
|
|
|
|
2010-11-10 19:00:48 +00:00
|
|
|
SEE ALSO
|
|
|
|
--------
|
2013-01-06 16:58:13 +00:00
|
|
|
linkgit:git-rm[1],
|
|
|
|
linkgit:gitrepository-layout[5],
|
|
|
|
linkgit:git-check-ignore[1]
|
2010-11-10 19:00:48 +00:00
|
|
|
|
2007-06-02 17:08:54 +00:00
|
|
|
GIT
|
|
|
|
---
|
2008-06-06 07:07:32 +00:00
|
|
|
Part of the linkgit:git[1] suite
|