dir.c: don't exclude whole dir prematurely if neg pattern may match
[git/git.git] / Documentation / gitignore.txt
CommitLineData
cedb8d5d
JT
1gitignore(5)
2============
3
4NAME
5----
6gitignore - Specifies intentionally untracked files to ignore
7
8SYNOPSIS
9--------
2ce66e2a 10$HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore
cedb8d5d
JT
11
12DESCRIPTION
13-----------
14
15A `gitignore` file specifies intentionally untracked files that
2de9b711
TA
16Git should ignore.
17Files already tracked by Git are not affected; see the NOTES
6f02a5a3 18below for details.
cedb8d5d 19
6259ac66 20Each line in a `gitignore` file specifies a pattern.
2de9b711 21When deciding whether to ignore a path, Git normally checks
cedb8d5d 22`gitignore` patterns from multiple sources, with the following
98ec4ad7
DK
23order of precedence, from highest to lowest (within one level of
24precedence, the last matching pattern decides the outcome):
cedb8d5d 25
98ec4ad7
DK
26 * Patterns read from the command line for those commands that support
27 them.
cedb8d5d
JT
28
29 * Patterns read from a `.gitignore` file in the same directory
98ec4ad7 30 as the path, or in any parent directory, with patterns in the
20ff3ec2
JM
31 higher level files (up to the toplevel of the work tree) being overridden
32 by those in lower level files down to the directory containing the file.
cedb8d5d
JT
33 These patterns match relative to the location of the
34 `.gitignore` file. A project normally includes such
35 `.gitignore` files in its repository, containing patterns for
36 files generated as part of the project build.
37
98ec4ad7
DK
38 * Patterns read from `$GIT_DIR/info/exclude`.
39
40 * Patterns read from the file specified by the configuration
41 variable 'core.excludesfile'.
42
90b22907 43Which file to place a pattern in depends on how the pattern is meant to
3f8c5a41
PO
44be used.
45
46 * Patterns which should be version-controlled and distributed to
47 other repositories via clone (i.e., files that all developers will want
48 to ignore) should go into a `.gitignore` file.
49
50 * Patterns which are
51 specific to a particular repository but which do not need to be shared
52 with other related repositories (e.g., auxiliary files that live inside
53 the repository but are specific to one user's workflow) should go into
54 the `$GIT_DIR/info/exclude` file.
55
2de9b711 56 * Patterns which a user wants Git to
3f8c5a41
PO
57 ignore in all situations (e.g., backup or temporary files generated by
58 the user's editor of choice) generally go into a file specified by
59 `core.excludesfile` in the user's `~/.gitconfig`. Its default value is
60 $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or
61 empty, $HOME/.config/git/ignore is used instead.
90b22907 62
2de9b711 63The underlying Git plumbing tools, such as
0b444cdb 64'git ls-files' and 'git read-tree', read
cedb8d5d 65`gitignore` patterns specified by command-line options, or from
2de9b711 66files specified by command-line options. Higher-level Git
0b444cdb 67tools, such as 'git status' and 'git add',
cedb8d5d
JT
68use patterns from the sources specified above.
69
0b803a6c
JN
70PATTERN FORMAT
71--------------
cedb8d5d
JT
72
73 - A blank line matches no files, so it can serve as a separator
74 for readability.
75
76 - A line starting with # serves as a comment.
866f5f82
NTND
77 Put a backslash ("`\`") in front of the first hash for patterns
78 that begin with a hash.
cedb8d5d 79
03af7cd1 80 - Trailing spaces are ignored unless they are quoted with backslash
7e2e4b37
NTND
81 ("`\`").
82
866f5f82 83 - An optional prefix "`!`" which negates the pattern; any
cedb8d5d 84 matching file excluded by a previous pattern will become
57534ee7 85 included again.
866f5f82
NTND
86 Put a backslash ("`\`") in front of the first "`!`" for patterns
87 that begin with a literal "`!`", for example, "`\!important!.txt`".
57534ee7
NTND
88 It is possible to re-include a file if a parent directory of that
89 file is excluded if certain conditions are met. See section NOTES
90 for detail.
cedb8d5d 91
d6b8fc30
JH
92 - If the pattern ends with a slash, it is removed for the
93 purpose of the following description, but it would only find
94 a match with a directory. In other words, `foo/` will match a
95 directory `foo` and paths underneath it, but will not match a
96 regular file or a symbolic link `foo` (this is consistent
2de9b711 97 with the way how pathspec works in general in Git).
d6b8fc30 98
2de9b711 99 - If the pattern does not contain a slash '/', Git treats it as
cedb8d5d 100 a shell glob pattern and checks for a match against the
81c13fde
JN
101 pathname relative to the location of the `.gitignore` file
102 (relative to the toplevel of the work tree if not from a
103 `.gitignore` file).
cedb8d5d 104
2de9b711 105 - Otherwise, Git treats the pattern as a shell glob suitable
cedb8d5d
JT
106 for consumption by fnmatch(3) with the FNM_PATHNAME flag:
107 wildcards in the pattern will not match a / in the pathname.
9257a1ef 108 For example, "Documentation/{asterisk}.html" matches
81c13fde
JN
109 "Documentation/git.html" but not "Documentation/ppc/ppc.html"
110 or "tools/perf/Documentation/perf.html".
111
112 - A leading slash matches the beginning of the pathname.
9257a1ef 113 For example, "/{asterisk}.c" matches "cat-file.c" but not
81c13fde 114 "mozilla-sha1/sha1.c".
cedb8d5d 115
237ec6e4
NTND
116Two consecutive asterisks ("`**`") in patterns matched against
117full pathname may have special meaning:
118
119 - A leading "`**`" followed by a slash means match in all
120 directories. For example, "`**/foo`" matches file or directory
8447dc89 121 "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`"
237ec6e4
NTND
122 matches file or directory "`bar`" anywhere that is directly
123 under directory "`foo`".
124
8447dc89
KB
125 - A trailing "`/**`" matches everything inside. For example,
126 "`abc/**`" matches all files inside directory "`abc`", relative
237ec6e4
NTND
127 to the location of the `.gitignore` file, with infinite depth.
128
129 - A slash followed by two consecutive asterisks then a slash
130 matches zero or more directories. For example, "`a/**/b`"
131 matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
132
133 - Other consecutive asterisks are considered invalid.
134
6f02a5a3
JN
135NOTES
136-----
137
138The purpose of gitignore files is to ensure that certain files
2de9b711 139not tracked by Git remain untracked.
6f02a5a3 140
6f02a5a3
JN
141To stop tracking a file that is currently tracked, use
142'git rm --cached'.
143
57534ee7
NTND
144To re-include files or directories when their parent directory is
145excluded, the following conditions must be met:
146
147 - The rules to exclude a directory and re-include a subset back must
148 be in the same .gitignore file.
149
150 - The directory part in the re-include rules must be literal (i.e. no
151 wildcards)
152
153 - The rules to exclude the parent directory must not end with a
154 trailing slash.
155
156 - The rules to exclude the parent directory must have at least one
157 slash.
158
0b803a6c
JN
159EXAMPLES
160--------
cedb8d5d
JT
161
162--------------------------------------------------------------
b1889c36 163 $ git status
cedb8d5d
JT
164 [...]
165 # Untracked files:
166 [...]
167 # Documentation/foo.html
168 # Documentation/gitignore.html
169 # file.o
170 # lib.a
171 # src/internal.o
172 [...]
173 $ cat .git/info/exclude
174 # ignore objects and archives, anywhere in the tree.
175 *.[oa]
176 $ cat Documentation/.gitignore
177 # ignore generated html files,
178 *.html
179 # except foo.html which is maintained by hand
180 !foo.html
b1889c36 181 $ git status
cedb8d5d
JT
182 [...]
183 # Untracked files:
184 [...]
185 # Documentation/foo.html
186 [...]
187--------------------------------------------------------------
188
189Another example:
190
191--------------------------------------------------------------
192 $ cat .gitignore
193 vmlinux*
194 $ ls arch/foo/kernel/vm*
195 arch/foo/kernel/vmlinux.lds.S
196 $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
197--------------------------------------------------------------
198
2de9b711 199The second .gitignore prevents Git from ignoring
cedb8d5d
JT
200`arch/foo/kernel/vmlinux.lds.S`.
201
59856de1
KB
202Example to exclude everything except a specific directory `foo/bar`
203(note the `/*` - without the slash, the wildcard would also exclude
204everything within `foo/bar`):
205
206--------------------------------------------------------------
207 $ cat .gitignore
208 # exclude everything except directory foo/bar
209 /*
210 !/foo
211 /foo/*
212 !/foo/bar
213--------------------------------------------------------------
214
6f02a5a3
JN
215SEE ALSO
216--------
368aa529 217linkgit:git-rm[1],
368aa529
AS
218linkgit:gitrepository-layout[5],
219linkgit:git-check-ignore[1]
6f02a5a3 220
cedb8d5d
JT
221GIT
222---
9e1f0a85 223Part of the linkgit:git[1] suite