man5/gitignore.5

   1 '\" t
   2 .\"     Title: gitignore
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-30
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.0.rc0.18.ge9356ba3ea
   8 .\"  Language: English
   9 .\"
  10 .TH "GITIGNORE" "5" "2024-09-30" "Git 2\&.47\&.0\&.rc0\&.18\&.ge" "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 "\fB/\fR" is used as the directory separator\&. Separators may occur at the beginning, middle or end of the
 191 \fB\&.gitignore\fR
 192 search pattern\&.
 193 .RE
 194 .sp
 195 .RS 4
 196 .ie n \{\
 197 \h'-04'\(bu\h'+03'\c
 198 .\}
 199 .el \{\
 200 .sp -1
 201 .IP \(bu 2.3
 202 .\}
 203 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
 204 \fB\&.gitignore\fR
 205 file itself\&. Otherwise the pattern may also match at any level below the
 206 \fB\&.gitignore\fR
 207 level\&.
 208 .RE
 209 .sp
 210 .RS 4
 211 .ie n \{\
 212 \h'-04'\(bu\h'+03'\c
 213 .\}
 214 .el \{\
 215 .sp -1
 216 .IP \(bu 2.3
 217 .\}
 218 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\&.
 219 .RE
 220 .sp
 221 .RS 4
 222 .ie n \{\
 223 \h'-04'\(bu\h'+03'\c
 224 .\}
 225 .el \{\
 226 .sp -1
 227 .IP \(bu 2.3
 228 .\}
 229 For example, a pattern
 230 \fBdoc/frotz/\fR
 231 matches
 232 \fBdoc/frotz\fR
 233 directory, but not
 234 \fBa/doc/frotz\fR
 235 directory; however
 236 \fBfrotz/\fR
 237 matches
 238 \fBfrotz\fR
 239 and
 240 \fBa/frotz\fR
 241 that is a directory (all paths are relative from the
 242 \fB\&.gitignore\fR
 243 file)\&.
 244 .RE
 245 .sp
 246 .RS 4
 247 .ie n \{\
 248 \h'-04'\(bu\h'+03'\c
 249 .\}
 250 .el \{\
 251 .sp -1
 252 .IP \(bu 2.3
 253 .\}
 254 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\&.
 255 \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\&.
 256 .RE
 257 .sp
 258 Two consecutive asterisks ("\fB**\fR") in patterns matched against full pathname may have special meaning:
 259 .sp
 260 .RS 4
 261 .ie n \{\
 262 \h'-04'\(bu\h'+03'\c
 263 .\}
 264 .el \{\
 265 .sp -1
 266 .IP \(bu 2.3
 267 .\}
 268 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"\&.
 269 .RE
 270 .sp
 271 .RS 4
 272 .ie n \{\
 273 \h'-04'\(bu\h'+03'\c
 274 .\}
 275 .el \{\
 276 .sp -1
 277 .IP \(bu 2.3
 278 .\}
 279 A trailing "\fB/**\fR" matches everything inside\&. For example, "\fBabc/**\fR" matches all files inside directory "\fBabc\fR", relative to the location of the
 280 \fB\&.gitignore\fR
 281 file, with infinite depth\&.
 282 .RE
 283 .sp
 284 .RS 4
 285 .ie n \{\
 286 \h'-04'\(bu\h'+03'\c
 287 .\}
 288 .el \{\
 289 .sp -1
 290 .IP \(bu 2.3
 291 .\}
 292 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\&.
 293 .RE
 294 .sp
 295 .RS 4
 296 .ie n \{\
 297 \h'-04'\(bu\h'+03'\c
 298 .\}
 299 .el \{\
 300 .sp -1
 301 .IP \(bu 2.3
 302 .\}
 303 Other consecutive asterisks are considered regular asterisks and will match according to the previous rules\&.
 304 .RE
 305 .SH "CONFIGURATION"
 306 .sp
 307 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\&.
 308 .SH "NOTES"
 309 .sp
 310 The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked\&.
 311 .sp
 312 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\&.
 313 .sp
 314 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\&.
 315 .SH "EXAMPLES"
 316 .sp
 317 .RS 4
 318 .ie n \{\
 319 \h'-04'\(bu\h'+03'\c
 320 .\}
 321 .el \{\
 322 .sp -1
 323 .IP \(bu 2.3
 324 .\}
 325 The pattern
 326 \fBhello\&.*\fR
 327 matches any file or directory whose name begins with
 328 \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\&.
 329 \fB/hello\&.*\fR; the pattern now matches
 330 \fBhello\&.txt\fR,
 331 \fBhello\&.c\fR
 332 but not
 333 \fBa/hello\&.java\fR\&.
 334 .RE
 335 .sp
 336 .RS 4
 337 .ie n \{\
 338 \h'-04'\(bu\h'+03'\c
 339 .\}
 340 .el \{\
 341 .sp -1
 342 .IP \(bu 2.3
 343 .\}
 344 The pattern
 345 \fBfoo/\fR
 346 will match a directory
 347 \fBfoo\fR
 348 and paths underneath it, but will not match a regular file or a symbolic link
 349 \fBfoo\fR
 350 (this is consistent with the way how pathspec works in general in Git)
 351 .RE
 352 .sp
 353 .RS 4
 354 .ie n \{\
 355 \h'-04'\(bu\h'+03'\c
 356 .\}
 357 .el \{\
 358 .sp -1
 359 .IP \(bu 2.3
 360 .\}
 361 The pattern
 362 \fBdoc/frotz\fR
 363 and
 364 \fB/doc/frotz\fR
 365 have the same effect in any
 366 \fB\&.gitignore\fR
 367 file\&. In other words, a leading slash is not relevant if there is already a middle slash in the pattern\&.
 368 .RE
 369 .sp
 370 .RS 4
 371 .ie n \{\
 372 \h'-04'\(bu\h'+03'\c
 373 .\}
 374 .el \{\
 375 .sp -1
 376 .IP \(bu 2.3
 377 .\}
 378 The pattern
 379 \fBfoo/*\fR, matches
 380 \fBfoo/test\&.json\fR
 381 (a regular file),
 382 \fBfoo/bar\fR
 383 (a directory), but it does not match
 384 \fBfoo/bar/hello\&.c\fR
 385 (a regular file), as the asterisk in the pattern does not match
 386 \fBbar/hello\&.c\fR
 387 which has a slash in it\&.
 388 .RE
 389 .sp
 390 .if n \{\
 391 .RS 4
 392 .\}
 393 .nf
 394     $ git status
 395     [\&.\&.\&.]
 396     # Untracked files:
 397     [\&.\&.\&.]
 398     #       Documentation/foo\&.html
 399     #       Documentation/gitignore\&.html
 400     #       file\&.o
 401     #       lib\&.a
 402     #       src/internal\&.o
 403     [\&.\&.\&.]
 404     $ cat \&.git/info/exclude
 405     # ignore objects and archives, anywhere in the tree\&.
 406     *\&.[oa]
 407     $ cat Documentation/\&.gitignore
 408     # ignore generated html files,
 409     *\&.html
 410     # except foo\&.html which is maintained by hand
 411     !foo\&.html
 412     $ git status
 413     [\&.\&.\&.]
 414     # Untracked files:
 415     [\&.\&.\&.]
 416     #       Documentation/foo\&.html
 417     [\&.\&.\&.]
 418 .fi
 419 .if n \{\
 420 .RE
 421 .\}
 422 .sp
 423 Another example:
 424 .sp
 425 .if n \{\
 426 .RS 4
 427 .\}
 428 .nf
 429     $ cat \&.gitignore
 430     vmlinux*
 431     $ ls arch/foo/kernel/vm*
 432     arch/foo/kernel/vmlinux\&.lds\&.S
 433     $ echo \*(Aq!/vmlinux*\*(Aq >arch/foo/kernel/\&.gitignore
 434 .fi
 435 .if n \{\
 436 .RE
 437 .\}
 438 .sp
 439 The second \&.gitignore prevents Git from ignoring \fBarch/foo/kernel/vmlinux\&.lds\&.S\fR\&.
 440 .sp
 441 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):
 442 .sp
 443 .if n \{\
 444 .RS 4
 445 .\}
 446 .nf
 447     $ cat \&.gitignore
 448     # exclude everything except directory foo/bar
 449     /*
 450     !/foo
 451     /foo/*
 452     !/foo/bar
 453 .fi
 454 .if n \{\
 455 .RE
 456 .\}
 457 .SH "SEE ALSO"
 458 .sp
 459 \fBgit-rm\fR(1), \fBgitrepository-layout\fR(5), \fBgit-check-ignore\fR(1)
 460 .SH "GIT"
 461 .sp
 462 Part of the \fBgit\fR(1) suite