]>
Commit | Line | Data |
---|---|---|
cedb8d5d JT |
1 | gitignore(5) |
2 | ============ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | gitignore - Specifies intentionally untracked files to ignore | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
45e851cb | 10 | $XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, .gitignore |
cedb8d5d JT |
11 | |
12 | DESCRIPTION | |
13 | ----------- | |
14 | ||
15 | A `gitignore` file specifies intentionally untracked files that | |
2de9b711 TA |
16 | Git should ignore. |
17 | Files already tracked by Git are not affected; see the NOTES | |
6f02a5a3 | 18 | below for details. |
cedb8d5d | 19 | |
6259ac66 | 20 | Each line in a `gitignore` file specifies a pattern. |
2de9b711 | 21 | When deciding whether to ignore a path, Git normally checks |
cedb8d5d | 22 | `gitignore` patterns from multiple sources, with the following |
98ec4ad7 DK |
23 | order of precedence, from highest to lowest (within one level of |
24 | precedence, 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 | 43 | Which file to place a pattern in depends on how the pattern is meant to |
3f8c5a41 PO |
44 | be 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 | 63 | The 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 | 66 | files specified by command-line options. Higher-level Git |
0b444cdb | 67 | tools, such as 'git status' and 'git add', |
cedb8d5d JT |
68 | use patterns from the sources specified above. |
69 | ||
0b803a6c JN |
70 | PATTERN 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 | |
1a58bad0 DAN |
92 | - The slash '/' is used as the directory separator. Separators may |
93 | occur at the beginning, middle or end of the `.gitignore` search pattern. | |
94 | ||
95 | - If there is a separator at the beginning or middle (or both) of the | |
96 | pattern, then the pattern is relative to the directory level of the | |
97 | particular `.gitignore` file itself. Otherwise the pattern may also | |
98 | match at any level below the `.gitignore` level. | |
99 | ||
100 | - If there is a separator at the end of the pattern then the pattern | |
101 | will only match directories, otherwise the pattern can match both | |
102 | files and directories. | |
103 | ||
104 | - For example, a pattern `doc/frotz/` matches `doc/frotz` directory, | |
105 | but not `a/doc/frotz` directory; however `frotz/` matches `frotz` | |
106 | and `a/frotz` that is a directory (all paths are relative from | |
107 | the `.gitignore` file). | |
108 | ||
109 | - An asterisk "`*`" matches anything except a slash. | |
110 | The character "`?`" matches any one character except "`/`". | |
111 | The range notation, e.g. `[a-zA-Z]`, can be used to match | |
112 | one of the characters in a range. See fnmatch(3) and the | |
113 | FNM_PATHNAME flag for a more detailed description. | |
cedb8d5d | 114 | |
237ec6e4 NTND |
115 | Two consecutive asterisks ("`**`") in patterns matched against |
116 | full 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 |
135 | CONFIGURATION |
136 | ------------- | |
137 | ||
138 | The optional configuration variable `core.excludesFile` indicates a path to a | |
139 | file containing patterns of file names to exclude, similar to | |
140 | `$GIT_DIR/info/exclude`. Patterns in the exclude file are used in addition to | |
141 | those in `$GIT_DIR/info/exclude`. | |
142 | ||
6f02a5a3 JN |
143 | NOTES |
144 | ----- | |
145 | ||
146 | The purpose of gitignore files is to ensure that certain files | |
2de9b711 | 147 | not tracked by Git remain untracked. |
6f02a5a3 | 148 | |
6f02a5a3 JN |
149 | To stop tracking a file that is currently tracked, use |
150 | 'git rm --cached'. | |
151 | ||
0b803a6c JN |
152 | EXAMPLES |
153 | -------- | |
cedb8d5d | 154 | |
1a58bad0 DAN |
155 | - The pattern `hello.*` matches any file or folder |
156 | whose name begins with `hello`. If one wants to restrict | |
157 | this only to the directory and not in its subdirectories, | |
158 | one can prepend the pattern with a slash, i.e. `/hello.*`; | |
159 | the pattern now matches `hello.txt`, `hello.c` but not | |
160 | `a/hello.java`. | |
161 | ||
162 | - The pattern `foo/` will match a directory `foo` and | |
163 | paths underneath it, but will not match a regular file | |
164 | or a symbolic link `foo` (this is consistent with the | |
165 | way how pathspec works in general in Git) | |
166 | ||
167 | - The pattern `doc/frotz` and `/doc/frotz` have the same effect | |
168 | in any `.gitignore` file. In other words, a leading slash | |
169 | is not relevant if there is already a middle slash in | |
170 | the pattern. | |
171 | ||
172 | - The pattern "foo/*", matches "foo/test.json" | |
173 | (a regular file), "foo/bar" (a directory), but it does not match | |
174 | "foo/bar/hello.c" (a regular file), as the asterisk in the | |
175 | pattern does not match "bar/hello.c" which has a slash in it. | |
176 | ||
cedb8d5d | 177 | -------------------------------------------------------------- |
b1889c36 | 178 | $ git status |
cedb8d5d JT |
179 | [...] |
180 | # Untracked files: | |
181 | [...] | |
182 | # Documentation/foo.html | |
183 | # Documentation/gitignore.html | |
184 | # file.o | |
185 | # lib.a | |
186 | # src/internal.o | |
187 | [...] | |
188 | $ cat .git/info/exclude | |
189 | # ignore objects and archives, anywhere in the tree. | |
190 | *.[oa] | |
191 | $ cat Documentation/.gitignore | |
192 | # ignore generated html files, | |
193 | *.html | |
194 | # except foo.html which is maintained by hand | |
195 | !foo.html | |
b1889c36 | 196 | $ git status |
cedb8d5d JT |
197 | [...] |
198 | # Untracked files: | |
199 | [...] | |
200 | # Documentation/foo.html | |
201 | [...] | |
202 | -------------------------------------------------------------- | |
203 | ||
204 | Another example: | |
205 | ||
206 | -------------------------------------------------------------- | |
207 | $ cat .gitignore | |
208 | vmlinux* | |
209 | $ ls arch/foo/kernel/vm* | |
210 | arch/foo/kernel/vmlinux.lds.S | |
211 | $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore | |
212 | -------------------------------------------------------------- | |
213 | ||
2de9b711 | 214 | The second .gitignore prevents Git from ignoring |
cedb8d5d JT |
215 | `arch/foo/kernel/vmlinux.lds.S`. |
216 | ||
59856de1 KB |
217 | Example to exclude everything except a specific directory `foo/bar` |
218 | (note the `/*` - without the slash, the wildcard would also exclude | |
219 | everything within `foo/bar`): | |
220 | ||
221 | -------------------------------------------------------------- | |
222 | $ cat .gitignore | |
223 | # exclude everything except directory foo/bar | |
224 | /* | |
225 | !/foo | |
226 | /foo/* | |
227 | !/foo/bar | |
228 | -------------------------------------------------------------- | |
229 | ||
6f02a5a3 JN |
230 | SEE ALSO |
231 | -------- | |
368aa529 | 232 | linkgit:git-rm[1], |
368aa529 AS |
233 | linkgit:gitrepository-layout[5], |
234 | linkgit:git-check-ignore[1] | |
6f02a5a3 | 235 | |
cedb8d5d JT |
236 | GIT |
237 | --- | |
9e1f0a85 | 238 | Part of the linkgit:git[1] suite |