| blob | 27da1a0d0ffbda28d853580a66d6f5e81f8c7703 |
1 '\" t
2 .\" Title: gitignore
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 12/28/2022
6 .\" Manual: Git Manual
7 .\" Source: Git 2.39.0.137.g6bae53b138
8 .\" Language: English
9 .\"
10 .TH "GITIGNORE" "5" "12/28/2022" "Git 2\&.39\&.0\&.137\&.g6bae53" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 gitignore \- Specifies intentionally untracked files to ignore
32 .SH "SYNOPSIS"
33 .sp
34 $XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, \&.gitignore
35 .SH "DESCRIPTION"
36 .sp
37 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\&.
38 .sp
39 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):
40 .sp
41 .RS 4
42 .ie n \{\
43 \h'-04'\(bu\h'+03'\c
44 .\}
45 .el \{\
46 .sp -1
47 .IP \(bu 2.3
48 .\}
49 Patterns read from the command line for those commands that support them\&.
50 .RE
51 .sp
52 .RS 4
53 .ie n \{\
54 \h'-04'\(bu\h'+03'\c
55 .\}
56 .el \{\
57 .sp -1
58 .IP \(bu 2.3
59 .\}
60 Patterns read from a
61 \fB\&.gitignore\fR
62 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
63 \fB\&.gitignore\fR
64 file\&. A project normally includes such
65 \fB\&.gitignore\fR
66 files in its repository, containing patterns for files generated as part of the project build\&.
67 .RE
68 .sp
69 .RS 4
70 .ie n \{\
71 \h'-04'\(bu\h'+03'\c
72 .\}
73 .el \{\
74 .sp -1
75 .IP \(bu 2.3
76 .\}
77 Patterns read from
78 \fB$GIT_DIR/info/exclude\fR\&.
79 .RE
80 .sp
81 .RS 4
82 .ie n \{\
83 \h'-04'\(bu\h'+03'\c
84 .\}
85 .el \{\
86 .sp -1
87 .IP \(bu 2.3
88 .\}
89 Patterns read from the file specified by the configuration variable
90 \fBcore\&.excludesFile\fR\&.
91 .RE
92 .sp
93 Which file to place a pattern in depends on how the pattern is meant to be used\&.
94 .sp
95 .RS 4
96 .ie n \{\
97 \h'-04'\(bu\h'+03'\c
98 .\}
99 .el \{\
100 .sp -1
101 .IP \(bu 2.3
102 .\}
103 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
104 \fB\&.gitignore\fR
105 file\&.
106 .RE
107 .sp
108 .RS 4
109 .ie n \{\
110 \h'-04'\(bu\h'+03'\c
111 .\}
112 .el \{\
113 .sp -1
114 .IP \(bu 2.3
115 .\}
116 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
117 \fB$GIT_DIR/info/exclude\fR
118 file\&.
119 .RE
120 .sp
121 .RS 4
122 .ie n \{\
123 \h'-04'\(bu\h'+03'\c
124 .\}
125 .el \{\
126 .sp -1
127 .IP \(bu 2.3
128 .\}
129 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
130 \fBcore\&.excludesFile\fR
131 in the user\(cqs
132 \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\&.
133 .RE
134 .sp
135 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\&.
136 .SH "PATTERN FORMAT"
137 .sp
138 .RS 4
139 .ie n \{\
140 \h'-04'\(bu\h'+03'\c
141 .\}
142 .el \{\
143 .sp -1
144 .IP \(bu 2.3
145 .\}
146 A blank line matches no files, so it can serve as a separator for readability\&.
147 .RE
148 .sp
149 .RS 4
150 .ie n \{\
151 \h'-04'\(bu\h'+03'\c
152 .\}
153 .el \{\
154 .sp -1
155 .IP \(bu 2.3
156 .\}
157 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\&.
158 .RE
159 .sp
160 .RS 4
161 .ie n \{\
162 \h'-04'\(bu\h'+03'\c
163 .\}
164 .el \{\
165 .sp -1
166 .IP \(bu 2.3
167 .\}
168 Trailing spaces are ignored unless they are quoted with backslash ("\fB\e\fR")\&.
169 .RE
170 .sp
171 .RS 4
172 .ie n \{\
173 \h'-04'\(bu\h'+03'\c
174 .\}
175 .el \{\
176 .sp -1
177 .IP \(bu 2.3
178 .\}
179 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"\&.
180 .RE
181 .sp
182 .RS 4
183 .ie n \{\
184 \h'-04'\(bu\h'+03'\c
185 .\}
186 .el \{\
187 .sp -1
188 .IP \(bu 2.3
189 .\}
190 The slash
191 \fI/\fR
192 is used as the directory separator\&. Separators may occur at the beginning, middle or end of the
193 \fB\&.gitignore\fR
194 search pattern\&.
195 .RE
196 .sp
197 .RS 4
198 .ie n \{\
199 \h'-04'\(bu\h'+03'\c
200 .\}
201 .el \{\
202 .sp -1
203 .IP \(bu 2.3
204 .\}
205 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
206 \fB\&.gitignore\fR
207 file itself\&. Otherwise the pattern may also match at any level below the
208 \fB\&.gitignore\fR
209 level\&.
210 .RE
211 .sp
212 .RS 4
213 .ie n \{\
214 \h'-04'\(bu\h'+03'\c
215 .\}
216 .el \{\
217 .sp -1
218 .IP \(bu 2.3
219 .\}
220 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\&.
221 .RE
222 .sp
223 .RS 4
224 .ie n \{\
225 \h'-04'\(bu\h'+03'\c
226 .\}
227 .el \{\
228 .sp -1
229 .IP \(bu 2.3
230 .\}
231 For example, a pattern
232 \fBdoc/frotz/\fR
233 matches
234 \fBdoc/frotz\fR
235 directory, but not
236 \fBa/doc/frotz\fR
237 directory; however
238 \fBfrotz/\fR
239 matches
240 \fBfrotz\fR
241 and
242 \fBa/frotz\fR
243 that is a directory (all paths are relative from the
244 \fB\&.gitignore\fR
245 file)\&.
246 .RE
247 .sp
248 .RS 4
249 .ie n \{\
250 \h'-04'\(bu\h'+03'\c
251 .\}
252 .el \{\
253 .sp -1
254 .IP \(bu 2.3
255 .\}
256 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\&.
257 \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\&.
258 .RE
259 .sp
260 Two consecutive asterisks ("\fB**\fR") in patterns matched against full pathname may have special meaning:
261 .sp
262 .RS 4
263 .ie n \{\
264 \h'-04'\(bu\h'+03'\c
265 .\}
266 .el \{\
267 .sp -1
268 .IP \(bu 2.3
269 .\}
270 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"\&.
271 .RE
272 .sp
273 .RS 4
274 .ie n \{\
275 \h'-04'\(bu\h'+03'\c
276 .\}
277 .el \{\
278 .sp -1
279 .IP \(bu 2.3
280 .\}
281 A trailing "\fB/**\fR" matches everything inside\&. For example, "\fBabc/**\fR" matches all files inside directory "\fBabc\fR", relative to the location of the
282 \fB\&.gitignore\fR
283 file, with infinite depth\&.
284 .RE
285 .sp
286 .RS 4
287 .ie n \{\
288 \h'-04'\(bu\h'+03'\c
289 .\}
290 .el \{\
291 .sp -1
292 .IP \(bu 2.3
293 .\}
294 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\&.
295 .RE
296 .sp
297 .RS 4
298 .ie n \{\
299 \h'-04'\(bu\h'+03'\c
300 .\}
301 .el \{\
302 .sp -1
303 .IP \(bu 2.3
304 .\}
305 Other consecutive asterisks are considered regular asterisks and will match according to the previous rules\&.
306 .RE
307 .SH "CONFIGURATION"
308 .sp
309 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\&.
310 .SH "NOTES"
311 .sp
312 The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked\&.
313 .sp
314 To stop tracking a file that is currently tracked, use \fIgit rm \-\-cached\fR\&.
315 .sp
316 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\&.
317 .SH "EXAMPLES"
318 .sp
319 .RS 4
320 .ie n \{\
321 \h'-04'\(bu\h'+03'\c
322 .\}
323 .el \{\
324 .sp -1
325 .IP \(bu 2.3
326 .\}
327 The pattern
328 \fBhello\&.*\fR
329 matches any file or directory whose name begins with
330 \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\&.
331 \fB/hello\&.*\fR; the pattern now matches
332 \fBhello\&.txt\fR,
333 \fBhello\&.c\fR
334 but not
335 \fBa/hello\&.java\fR\&.
336 .RE
337 .sp
338 .RS 4
339 .ie n \{\
340 \h'-04'\(bu\h'+03'\c
341 .\}
342 .el \{\
343 .sp -1
344 .IP \(bu 2.3
345 .\}
346 The pattern
347 \fBfoo/\fR
348 will match a directory
349 \fBfoo\fR
350 and paths underneath it, but will not match a regular file or a symbolic link
351 \fBfoo\fR
352 (this is consistent with the way how pathspec works in general in Git)
353 .RE
354 .sp
355 .RS 4
356 .ie n \{\
357 \h'-04'\(bu\h'+03'\c
358 .\}
359 .el \{\
360 .sp -1
361 .IP \(bu 2.3
362 .\}
363 The pattern
364 \fBdoc/frotz\fR
365 and
366 \fB/doc/frotz\fR
367 have the same effect in any
368 \fB\&.gitignore\fR
369 file\&. In other words, a leading slash is not relevant if there is already a middle slash in the pattern\&.
370 .RE
371 .sp
372 .RS 4
373 .ie n \{\
374 \h'-04'\(bu\h'+03'\c
375 .\}
376 .el \{\
377 .sp -1
378 .IP \(bu 2.3
379 .\}
380 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\&.
381 .RE
382 .sp
383 .if n \{\
384 .RS 4
385 .\}
386 .nf
387 $ git status
388 [\&.\&.\&.]
389 # Untracked files:
390 [\&.\&.\&.]
391 # Documentation/foo\&.html
392 # Documentation/gitignore\&.html
393 # file\&.o
394 # lib\&.a
395 # src/internal\&.o
396 [\&.\&.\&.]
397 $ cat \&.git/info/exclude
398 # ignore objects and archives, anywhere in the tree\&.
399 *\&.[oa]
400 $ cat Documentation/\&.gitignore
401 # ignore generated html files,
402 *\&.html
403 # except foo\&.html which is maintained by hand
404 !foo\&.html
405 $ git status
406 [\&.\&.\&.]
407 # Untracked files:
408 [\&.\&.\&.]
409 # Documentation/foo\&.html
410 [\&.\&.\&.]
411 .fi
412 .if n \{\
413 .RE
414 .\}
415 .sp
416 .sp
417 Another example:
418 .sp
419 .if n \{\
420 .RS 4
421 .\}
422 .nf
423 $ cat \&.gitignore
424 vmlinux*
425 $ ls arch/foo/kernel/vm*
426 arch/foo/kernel/vmlinux\&.lds\&.S
427 $ echo \(aq!/vmlinux*\(aq >arch/foo/kernel/\&.gitignore
428 .fi
429 .if n \{\
430 .RE
431 .\}
432 .sp
433 .sp
434 The second \&.gitignore prevents Git from ignoring \fBarch/foo/kernel/vmlinux\&.lds\&.S\fR\&.
435 .sp
436 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):
437 .sp
438 .if n \{\
439 .RS 4
440 .\}
441 .nf
442 $ cat \&.gitignore
443 # exclude everything except directory foo/bar
444 /*
445 !/foo
446 /foo/*
447 !/foo/bar
448 .fi
449 .if n \{\
450 .RE
451 .\}
452 .sp
453 .SH "SEE ALSO"
454 .sp
455 \fBgit-rm\fR(1), \fBgitrepository-layout\fR(5), \fBgit-check-ignore\fR(1)
456 .SH "GIT"
457 .sp
458 Part of the \fBgit\fR(1) suite