logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

gitignore.5 (12113B)


  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: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GITIGNORE" "5" "2025-03-14" "Git 2\&.49\&.0" "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 \&.\fBgitignore\fR
  61. 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 \&.\fBgitignore\fR
  62. file\&. A project normally includes such \&.\fBgitignore\fR
  63. files in its repository, containing patterns for files generated as part of the project build\&.
  64. .RE
  65. .sp
  66. .RS 4
  67. .ie n \{\
  68. \h'-04'\(bu\h'+03'\c
  69. .\}
  70. .el \{\
  71. .sp -1
  72. .IP \(bu 2.3
  73. .\}
  74. Patterns read from
  75. \fB$GIT_DIR/info/exclude\fR\&.
  76. .RE
  77. .sp
  78. .RS 4
  79. .ie n \{\
  80. \h'-04'\(bu\h'+03'\c
  81. .\}
  82. .el \{\
  83. .sp -1
  84. .IP \(bu 2.3
  85. .\}
  86. Patterns read from the file specified by the configuration variable
  87. \fBcore\&.excludesFile\fR\&.
  88. .RE
  89. .sp
  90. Which file to place a pattern in depends on how the pattern is meant to be used\&.
  91. .sp
  92. .RS 4
  93. .ie n \{\
  94. \h'-04'\(bu\h'+03'\c
  95. .\}
  96. .el \{\
  97. .sp -1
  98. .IP \(bu 2.3
  99. .\}
  100. 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 \&.\fBgitignore\fR
  101. file\&.
  102. .RE
  103. .sp
  104. .RS 4
  105. .ie n \{\
  106. \h'-04'\(bu\h'+03'\c
  107. .\}
  108. .el \{\
  109. .sp -1
  110. .IP \(bu 2.3
  111. .\}
  112. 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
  113. \fB$GIT_DIR/info/exclude\fR
  114. file\&.
  115. .RE
  116. .sp
  117. .RS 4
  118. .ie n \{\
  119. \h'-04'\(bu\h'+03'\c
  120. .\}
  121. .el \{\
  122. .sp -1
  123. .IP \(bu 2.3
  124. .\}
  125. 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
  126. \fBcore\&.excludesFile\fR
  127. in the user\(cqs
  128. \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\&.
  129. .RE
  130. .sp
  131. 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\&.
  132. .SH "PATTERN FORMAT"
  133. .sp
  134. .RS 4
  135. .ie n \{\
  136. \h'-04'\(bu\h'+03'\c
  137. .\}
  138. .el \{\
  139. .sp -1
  140. .IP \(bu 2.3
  141. .\}
  142. A blank line matches no files, so it can serve as a separator for readability\&.
  143. .RE
  144. .sp
  145. .RS 4
  146. .ie n \{\
  147. \h'-04'\(bu\h'+03'\c
  148. .\}
  149. .el \{\
  150. .sp -1
  151. .IP \(bu 2.3
  152. .\}
  153. A line starting with # serves as a comment\&. Put a backslash ("\e") in front of the first hash for patterns that begin with a hash\&.
  154. .RE
  155. .sp
  156. .RS 4
  157. .ie n \{\
  158. \h'-04'\(bu\h'+03'\c
  159. .\}
  160. .el \{\
  161. .sp -1
  162. .IP \(bu 2.3
  163. .\}
  164. Trailing spaces are ignored unless they are quoted with backslash ("\e")\&.
  165. .RE
  166. .sp
  167. .RS 4
  168. .ie n \{\
  169. \h'-04'\(bu\h'+03'\c
  170. .\}
  171. .el \{\
  172. .sp -1
  173. .IP \(bu 2.3
  174. .\}
  175. An optional prefix "!" 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 ("\e") in front of the first "!" for patterns that begin with a literal "!", for example, "\e!important!\&.\fBtxt\fR"\&.
  176. .RE
  177. .sp
  178. .RS 4
  179. .ie n \{\
  180. \h'-04'\(bu\h'+03'\c
  181. .\}
  182. .el \{\
  183. .sp -1
  184. .IP \(bu 2.3
  185. .\}
  186. The slash "\fB/\fR" is used as the directory separator\&. Separators may occur at the beginning, middle or end of the \&.\fBgitignore\fR
  187. search pattern\&.
  188. .RE
  189. .sp
  190. .RS 4
  191. .ie n \{\
  192. \h'-04'\(bu\h'+03'\c
  193. .\}
  194. .el \{\
  195. .sp -1
  196. .IP \(bu 2.3
  197. .\}
  198. 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 \&.\fBgitignore\fR
  199. file itself\&. Otherwise the pattern may also match at any level below the \&.\fBgitignore\fR
  200. level\&.
  201. .RE
  202. .sp
  203. .RS 4
  204. .ie n \{\
  205. \h'-04'\(bu\h'+03'\c
  206. .\}
  207. .el \{\
  208. .sp -1
  209. .IP \(bu 2.3
  210. .\}
  211. 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\&.
  212. .RE
  213. .sp
  214. .RS 4
  215. .ie n \{\
  216. \h'-04'\(bu\h'+03'\c
  217. .\}
  218. .el \{\
  219. .sp -1
  220. .IP \(bu 2.3
  221. .\}
  222. For example, a pattern
  223. \fBdoc/frotz/\fR
  224. matches
  225. \fBdoc/frotz\fR
  226. directory, but not
  227. \fBa/doc/frotz\fR
  228. directory; however
  229. \fBfrotz/\fR
  230. matches
  231. \fBfrotz\fR
  232. and
  233. \fBa/frotz\fR
  234. that is a directory (all paths are relative from the \&.\fBgitignore\fR
  235. file)\&.
  236. .RE
  237. .sp
  238. .RS 4
  239. .ie n \{\
  240. \h'-04'\(bu\h'+03'\c
  241. .\}
  242. .el \{\
  243. .sp -1
  244. .IP \(bu 2.3
  245. .\}
  246. An asterisk "*" matches anything except a slash\&. The character "?" matches any one character except "\fB/\fR"\&. The range notation, e\&.g\&. [\fBa\-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\&.
  247. .RE
  248. .sp
  249. Two consecutive asterisks ("**") in patterns matched against full pathname may have special meaning:
  250. .sp
  251. .RS 4
  252. .ie n \{\
  253. \h'-04'\(bu\h'+03'\c
  254. .\}
  255. .el \{\
  256. .sp -1
  257. .IP \(bu 2.3
  258. .\}
  259. A leading "**" followed by a slash means match in all directories\&. For example, "**/foo" matches file or directory "\fBfoo\fR" anywhere, the same as pattern "\fBfoo\fR"\&. "**/foo/bar" matches file or directory "\fBbar\fR" anywhere that is directly under directory "\fBfoo\fR"\&.
  260. .RE
  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 trailing "\fB/\fR**" matches everything inside\&. For example, "\fBabc/\fR**" matches all files inside directory "\fBabc\fR", relative to the location of the \&.\fBgitignore\fR
  271. file, with infinite depth\&.
  272. .RE
  273. .sp
  274. .RS 4
  275. .ie n \{\
  276. \h'-04'\(bu\h'+03'\c
  277. .\}
  278. .el \{\
  279. .sp -1
  280. .IP \(bu 2.3
  281. .\}
  282. A slash followed by two consecutive asterisks then a slash matches zero or more directories\&. For example, "\fBa/\fR**/b" matches "\fBa/b\fR", "\fBa/x/b\fR", "\fBa/x/y/b\fR" and so on\&.
  283. .RE
  284. .sp
  285. .RS 4
  286. .ie n \{\
  287. \h'-04'\(bu\h'+03'\c
  288. .\}
  289. .el \{\
  290. .sp -1
  291. .IP \(bu 2.3
  292. .\}
  293. Other consecutive asterisks are considered regular asterisks and will match according to the previous rules\&.
  294. .RE
  295. .SH "CONFIGURATION"
  296. .sp
  297. 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\&.
  298. .SH "NOTES"
  299. .sp
  300. The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked\&.
  301. .sp
  302. 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 \&.\fBgitignore\fR file to stop the file from being reintroduced in later commits\&.
  303. .sp
  304. Git does not follow symbolic links when accessing a \&.\fBgitignore\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\&.
  305. .SH "EXAMPLES"
  306. .sp
  307. .RS 4
  308. .ie n \{\
  309. \h'-04'\(bu\h'+03'\c
  310. .\}
  311. .el \{\
  312. .sp -1
  313. .IP \(bu 2.3
  314. .\}
  315. The pattern
  316. \fBhello\&.\fR* matches any file or directory whose name begins with
  317. \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\&.
  318. \fB/hello\&.\fR*; the pattern now matches
  319. \fBhello\&.txt\fR,
  320. \fBhello\&.c\fR
  321. but not
  322. \fBa/hello\&.java\fR\&.
  323. .RE
  324. .sp
  325. .RS 4
  326. .ie n \{\
  327. \h'-04'\(bu\h'+03'\c
  328. .\}
  329. .el \{\
  330. .sp -1
  331. .IP \(bu 2.3
  332. .\}
  333. The pattern
  334. \fBfoo/\fR
  335. will match a directory
  336. \fBfoo\fR
  337. and paths underneath it, but will not match a regular file or a symbolic link
  338. \fBfoo\fR
  339. (this is consistent with the way how pathspec works in general in Git)
  340. .RE
  341. .sp
  342. .RS 4
  343. .ie n \{\
  344. \h'-04'\(bu\h'+03'\c
  345. .\}
  346. .el \{\
  347. .sp -1
  348. .IP \(bu 2.3
  349. .\}
  350. The pattern
  351. \fBdoc/frotz\fR
  352. and
  353. \fB/doc/frotz\fR
  354. have the same effect in any \&.\fBgitignore\fR
  355. file\&. In other words, a leading slash is not relevant if there is already a middle slash in the pattern\&.
  356. .RE
  357. .sp
  358. .RS 4
  359. .ie n \{\
  360. \h'-04'\(bu\h'+03'\c
  361. .\}
  362. .el \{\
  363. .sp -1
  364. .IP \(bu 2.3
  365. .\}
  366. The pattern
  367. \fBfoo/\fR*, matches
  368. \fBfoo/test\&.json\fR
  369. (a regular file),
  370. \fBfoo/bar\fR
  371. (a directory), but it does not match
  372. \fBfoo/bar/hello\&.c\fR
  373. (a regular file), as the asterisk in the pattern does not match
  374. \fBbar/hello\&.c\fR
  375. which has a slash in it\&.
  376. .RE
  377. .sp
  378. .if n \{\
  379. .RS 4
  380. .\}
  381. .nf
  382. $ git status
  383. [\&.\&.\&.]
  384. # Untracked files:
  385. [\&.\&.\&.]
  386. # Documentation/foo\&.html
  387. # Documentation/gitignore\&.html
  388. # file\&.o
  389. # lib\&.a
  390. # src/internal\&.o
  391. [\&.\&.\&.]
  392. $ cat \&.git/info/exclude
  393. # ignore objects and archives, anywhere in the tree\&.
  394. *\&.[oa]
  395. $ cat Documentation/\&.gitignore
  396. # ignore generated html files,
  397. *\&.html
  398. # except foo\&.html which is maintained by hand
  399. !foo\&.html
  400. $ git status
  401. [\&.\&.\&.]
  402. # Untracked files:
  403. [\&.\&.\&.]
  404. # Documentation/foo\&.html
  405. [\&.\&.\&.]
  406. .fi
  407. .if n \{\
  408. .RE
  409. .\}
  410. .sp
  411. Another example:
  412. .sp
  413. .if n \{\
  414. .RS 4
  415. .\}
  416. .nf
  417. $ cat \&.gitignore
  418. vmlinux*
  419. $ ls arch/foo/kernel/vm*
  420. arch/foo/kernel/vmlinux\&.lds\&.S
  421. $ echo \*(Aq!/vmlinux*\*(Aq >arch/foo/kernel/\&.gitignore
  422. .fi
  423. .if n \{\
  424. .RE
  425. .\}
  426. .sp
  427. The second \&.gitignore prevents Git from ignoring \fBarch/foo/kernel/vmlinux\&.lds\&.S\fR\&.
  428. .sp
  429. 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):
  430. .sp
  431. .if n \{\
  432. .RS 4
  433. .\}
  434. .nf
  435. $ cat \&.gitignore
  436. # exclude everything except directory foo/bar
  437. /*
  438. !/foo
  439. /foo/*
  440. !/foo/bar
  441. .fi
  442. .if n \{\
  443. .RE
  444. .\}
  445. .SH "SEE ALSO"
  446. .sp
  447. \fBgit-rm\fR(1), \fBgitrepository-layout\fR(5), \fBgit-check-ignore\fR(1)
  448. .SH "GIT"
  449. .sp
  450. Part of the \fBgit\fR(1) suite