]>
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 | |
e0417069 AB |
30 | as the path, or in any parent directory (up to the top-level of the working |
31 | tree), with patterns in the higher level files being overridden by those in | |
32 | lower level files down to the directory containing the file. These patterns | |
33 | match relative to the location of the `.gitignore` file. A project normally | |
34 | includes such `.gitignore` files in its repository, containing patterns for | |
cedb8d5d JT |
35 | files generated as part of the project build. |
36 | ||
98ec4ad7 DK |
37 | * Patterns read from `$GIT_DIR/info/exclude`. |
38 | ||
39 | * Patterns read from the file specified by the configuration | |
ae9f6311 | 40 | variable `core.excludesFile`. |
98ec4ad7 | 41 | |
90b22907 | 42 | Which file to place a pattern in depends on how the pattern is meant to |
3f8c5a41 PO |
43 | be used. |
44 | ||
45 | * Patterns which should be version-controlled and distributed to | |
46 | other repositories via clone (i.e., files that all developers will want | |
47 | to ignore) should go into a `.gitignore` file. | |
48 | ||
49 | * Patterns which are | |
50 | specific to a particular repository but which do not need to be shared | |
51 | with other related repositories (e.g., auxiliary files that live inside | |
52 | the repository but are specific to one user's workflow) should go into | |
53 | the `$GIT_DIR/info/exclude` file. | |
54 | ||
2de9b711 | 55 | * Patterns which a user wants Git to |
3f8c5a41 PO |
56 | ignore in all situations (e.g., backup or temporary files generated by |
57 | the user's editor of choice) generally go into a file specified by | |
da0005b8 | 58 | `core.excludesFile` in the user's `~/.gitconfig`. Its default value is |
3f8c5a41 PO |
59 | $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or |
60 | empty, $HOME/.config/git/ignore is used instead. | |
90b22907 | 61 | |
2de9b711 | 62 | The underlying Git plumbing tools, such as |
0b444cdb | 63 | 'git ls-files' and 'git read-tree', read |
cedb8d5d | 64 | `gitignore` patterns specified by command-line options, or from |
2de9b711 | 65 | files specified by command-line options. Higher-level Git |
0b444cdb | 66 | tools, such as 'git status' and 'git add', |
cedb8d5d JT |
67 | use patterns from the sources specified above. |
68 | ||
0b803a6c JN |
69 | PATTERN FORMAT |
70 | -------------- | |
cedb8d5d JT |
71 | |
72 | - A blank line matches no files, so it can serve as a separator | |
73 | for readability. | |
74 | ||
75 | - A line starting with # serves as a comment. | |
866f5f82 NTND |
76 | Put a backslash ("`\`") in front of the first hash for patterns |
77 | that begin with a hash. | |
cedb8d5d | 78 | |
03af7cd1 | 79 | - Trailing spaces are ignored unless they are quoted with backslash |
7e2e4b37 NTND |
80 | ("`\`"). |
81 | ||
866f5f82 | 82 | - An optional prefix "`!`" which negates the pattern; any |
cedb8d5d | 83 | matching file excluded by a previous pattern will become |
5cee3493 JH |
84 | included again. It is not possible to re-include a file if a parent |
85 | directory of that file is excluded. Git doesn't list excluded | |
86 | directories for performance reasons, so any patterns on contained | |
87 | files have no effect, no matter where they are defined. | |
866f5f82 NTND |
88 | Put a backslash ("`\`") in front of the first "`!`" for patterns |
89 | that begin with a literal "`!`", for example, "`\!important!.txt`". | |
cedb8d5d | 90 | |
1a58bad0 DAN |
91 | - The slash '/' is used as the directory separator. Separators may |
92 | occur at the beginning, middle or end of the `.gitignore` search pattern. | |
93 | ||
94 | - If there is a separator at the beginning or middle (or both) of the | |
95 | pattern, then the pattern is relative to the directory level of the | |
96 | particular `.gitignore` file itself. Otherwise the pattern may also | |
97 | match at any level below the `.gitignore` level. | |
98 | ||
99 | - If there is a separator at the end of the pattern then the pattern | |
100 | will only match directories, otherwise the pattern can match both | |
101 | files and directories. | |
102 | ||
103 | - For example, a pattern `doc/frotz/` matches `doc/frotz` directory, | |
104 | but not `a/doc/frotz` directory; however `frotz/` matches `frotz` | |
105 | and `a/frotz` that is a directory (all paths are relative from | |
106 | the `.gitignore` file). | |
107 | ||
108 | - An asterisk "`*`" matches anything except a slash. | |
109 | The character "`?`" matches any one character except "`/`". | |
110 | The range notation, e.g. `[a-zA-Z]`, can be used to match | |
111 | one of the characters in a range. See fnmatch(3) and the | |
112 | FNM_PATHNAME flag for a more detailed description. | |
cedb8d5d | 113 | |
237ec6e4 NTND |
114 | Two consecutive asterisks ("`**`") in patterns matched against |
115 | full pathname may have special meaning: | |
116 | ||
117 | - A leading "`**`" followed by a slash means match in all | |
118 | directories. For example, "`**/foo`" matches file or directory | |
8447dc89 | 119 | "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`" |
237ec6e4 NTND |
120 | matches file or directory "`bar`" anywhere that is directly |
121 | under directory "`foo`". | |
122 | ||
8447dc89 KB |
123 | - A trailing "`/**`" matches everything inside. For example, |
124 | "`abc/**`" matches all files inside directory "`abc`", relative | |
237ec6e4 NTND |
125 | to the location of the `.gitignore` file, with infinite depth. |
126 | ||
127 | - A slash followed by two consecutive asterisks then a slash | |
128 | matches zero or more directories. For example, "`a/**/b`" | |
129 | matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on. | |
130 | ||
e5bbe09e NTND |
131 | - Other consecutive asterisks are considered regular asterisks and |
132 | will match according to the previous rules. | |
237ec6e4 | 133 | |
af91b023 DL |
134 | CONFIGURATION |
135 | ------------- | |
136 | ||
137 | The optional configuration variable `core.excludesFile` indicates a path to a | |
138 | file containing patterns of file names to exclude, similar to | |
139 | `$GIT_DIR/info/exclude`. Patterns in the exclude file are used in addition to | |
140 | those in `$GIT_DIR/info/exclude`. | |
141 | ||
6f02a5a3 JN |
142 | NOTES |
143 | ----- | |
144 | ||
145 | The purpose of gitignore files is to ensure that certain files | |
2de9b711 | 146 | not tracked by Git remain untracked. |
6f02a5a3 | 147 | |
6f02a5a3 JN |
148 | To stop tracking a file that is currently tracked, use |
149 | 'git rm --cached'. | |
150 | ||
8ff06de1 JK |
151 | Git does not follow symbolic links when accessing a `.gitignore` file in |
152 | the working tree. This keeps behavior consistent when the file is | |
153 | accessed from the index or a tree versus from the filesystem. | |
154 | ||
0b803a6c JN |
155 | EXAMPLES |
156 | -------- | |
cedb8d5d | 157 | |
1a58bad0 | 158 | - The pattern `hello.*` matches any file or folder |
ea7e6392 | 159 | whose name begins with `hello.`. If one wants to restrict |
1a58bad0 DAN |
160 | this only to the directory and not in its subdirectories, |
161 | one can prepend the pattern with a slash, i.e. `/hello.*`; | |
162 | the pattern now matches `hello.txt`, `hello.c` but not | |
163 | `a/hello.java`. | |
164 | ||
165 | - The pattern `foo/` will match a directory `foo` and | |
166 | paths underneath it, but will not match a regular file | |
167 | or a symbolic link `foo` (this is consistent with the | |
168 | way how pathspec works in general in Git) | |
169 | ||
170 | - The pattern `doc/frotz` and `/doc/frotz` have the same effect | |
171 | in any `.gitignore` file. In other words, a leading slash | |
172 | is not relevant if there is already a middle slash in | |
173 | the pattern. | |
174 | ||
175 | - The pattern "foo/*", matches "foo/test.json" | |
176 | (a regular file), "foo/bar" (a directory), but it does not match | |
177 | "foo/bar/hello.c" (a regular file), as the asterisk in the | |
178 | pattern does not match "bar/hello.c" which has a slash in it. | |
179 | ||
cedb8d5d | 180 | -------------------------------------------------------------- |
b1889c36 | 181 | $ git status |
cedb8d5d JT |
182 | [...] |
183 | # Untracked files: | |
184 | [...] | |
185 | # Documentation/foo.html | |
186 | # Documentation/gitignore.html | |
187 | # file.o | |
188 | # lib.a | |
189 | # src/internal.o | |
190 | [...] | |
191 | $ cat .git/info/exclude | |
192 | # ignore objects and archives, anywhere in the tree. | |
193 | *.[oa] | |
194 | $ cat Documentation/.gitignore | |
195 | # ignore generated html files, | |
196 | *.html | |
197 | # except foo.html which is maintained by hand | |
198 | !foo.html | |
b1889c36 | 199 | $ git status |
cedb8d5d JT |
200 | [...] |
201 | # Untracked files: | |
202 | [...] | |
203 | # Documentation/foo.html | |
204 | [...] | |
205 | -------------------------------------------------------------- | |
206 | ||
207 | Another example: | |
208 | ||
209 | -------------------------------------------------------------- | |
210 | $ cat .gitignore | |
211 | vmlinux* | |
212 | $ ls arch/foo/kernel/vm* | |
213 | arch/foo/kernel/vmlinux.lds.S | |
214 | $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore | |
215 | -------------------------------------------------------------- | |
216 | ||
2de9b711 | 217 | The second .gitignore prevents Git from ignoring |
cedb8d5d JT |
218 | `arch/foo/kernel/vmlinux.lds.S`. |
219 | ||
59856de1 KB |
220 | Example to exclude everything except a specific directory `foo/bar` |
221 | (note the `/*` - without the slash, the wildcard would also exclude | |
222 | everything within `foo/bar`): | |
223 | ||
224 | -------------------------------------------------------------- | |
225 | $ cat .gitignore | |
226 | # exclude everything except directory foo/bar | |
227 | /* | |
228 | !/foo | |
229 | /foo/* | |
230 | !/foo/bar | |
231 | -------------------------------------------------------------- | |
232 | ||
6f02a5a3 JN |
233 | SEE ALSO |
234 | -------- | |
368aa529 | 235 | linkgit:git-rm[1], |
368aa529 AS |
236 | linkgit:gitrepository-layout[5], |
237 | linkgit:git-check-ignore[1] | |
6f02a5a3 | 238 | |
cedb8d5d JT |
239 | GIT |
240 | --- | |
9e1f0a85 | 241 | Part of the linkgit:git[1] suite |