docs: move core.excludesFile from git-add to gitignore
[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--------
45e851cb 10$XDG_CONFIG_HOME/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
ae9f6311 41 variable `core.excludesFile`.
98ec4ad7 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
da0005b8 59 `core.excludesFile` in the user's `~/.gitconfig`. Its default value is
3f8c5a41
PO
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
5cee3493
JH
85 included again. It is not possible to re-include a file if a parent
86 directory of that file is excluded. Git doesn't list excluded
87 directories for performance reasons, so any patterns on contained
88 files have no effect, no matter where they are defined.
866f5f82
NTND
89 Put a backslash ("`\`") in front of the first "`!`" for patterns
90 that begin with a literal "`!`", for example, "`\!important!.txt`".
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
2e22a85e
NTND
105 - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
106 anything except "`/`", "`?`" matches any one character except "`/`"
107 and "`[]`" matches one character in a selected range. See
108 fnmatch(3) and the FNM_PATHNAME flag for a more detailed
109 description.
81c13fde
JN
110
111 - A leading slash matches the beginning of the pathname.
9257a1ef 112 For example, "/{asterisk}.c" matches "cat-file.c" but not
81c13fde 113 "mozilla-sha1/sha1.c".
cedb8d5d 114
237ec6e4
NTND
115Two consecutive asterisks ("`**`") in patterns matched against
116full pathname may have special meaning:
117
118 - A leading "`**`" followed by a slash means match in all
119 directories. For example, "`**/foo`" matches file or directory
8447dc89 120 "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`"
237ec6e4
NTND
121 matches file or directory "`bar`" anywhere that is directly
122 under directory "`foo`".
123
8447dc89
KB
124 - A trailing "`/**`" matches everything inside. For example,
125 "`abc/**`" matches all files inside directory "`abc`", relative
237ec6e4
NTND
126 to the location of the `.gitignore` file, with infinite depth.
127
128 - A slash followed by two consecutive asterisks then a slash
129 matches zero or more directories. For example, "`a/**/b`"
130 matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
131
e5bbe09e
NTND
132 - Other consecutive asterisks are considered regular asterisks and
133 will match according to the previous rules.
237ec6e4 134
af91b023
DL
135CONFIGURATION
136-------------
137
138The optional configuration variable `core.excludesFile` indicates a path to a
139file containing patterns of file names to exclude, similar to
140`$GIT_DIR/info/exclude`. Patterns in the exclude file are used in addition to
141those in `$GIT_DIR/info/exclude`.
142
6f02a5a3
JN
143NOTES
144-----
145
146The purpose of gitignore files is to ensure that certain files
2de9b711 147not tracked by Git remain untracked.
6f02a5a3 148
6f02a5a3
JN
149To stop tracking a file that is currently tracked, use
150'git rm --cached'.
151
0b803a6c
JN
152EXAMPLES
153--------
cedb8d5d
JT
154
155--------------------------------------------------------------
b1889c36 156 $ git status
cedb8d5d
JT
157 [...]
158 # Untracked files:
159 [...]
160 # Documentation/foo.html
161 # Documentation/gitignore.html
162 # file.o
163 # lib.a
164 # src/internal.o
165 [...]
166 $ cat .git/info/exclude
167 # ignore objects and archives, anywhere in the tree.
168 *.[oa]
169 $ cat Documentation/.gitignore
170 # ignore generated html files,
171 *.html
172 # except foo.html which is maintained by hand
173 !foo.html
b1889c36 174 $ git status
cedb8d5d
JT
175 [...]
176 # Untracked files:
177 [...]
178 # Documentation/foo.html
179 [...]
180--------------------------------------------------------------
181
182Another example:
183
184--------------------------------------------------------------
185 $ cat .gitignore
186 vmlinux*
187 $ ls arch/foo/kernel/vm*
188 arch/foo/kernel/vmlinux.lds.S
189 $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
190--------------------------------------------------------------
191
2de9b711 192The second .gitignore prevents Git from ignoring
cedb8d5d
JT
193`arch/foo/kernel/vmlinux.lds.S`.
194
59856de1
KB
195Example to exclude everything except a specific directory `foo/bar`
196(note the `/*` - without the slash, the wildcard would also exclude
197everything within `foo/bar`):
198
199--------------------------------------------------------------
200 $ cat .gitignore
201 # exclude everything except directory foo/bar
202 /*
203 !/foo
204 /foo/*
205 !/foo/bar
206--------------------------------------------------------------
207
6f02a5a3
JN
208SEE ALSO
209--------
368aa529 210linkgit:git-rm[1],
368aa529
AS
211linkgit:gitrepository-layout[5],
212linkgit:git-check-ignore[1]
6f02a5a3 213
cedb8d5d
JT
214GIT
215---
9e1f0a85 216Part of the linkgit:git[1] suite