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 | -------- | |
2ce66e2a | 10 | $HOME/.config/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 | |
41 | variable 'core.excludesfile'. | |
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 | |
59 | `core.excludesfile` in the user's `~/.gitconfig`. Its default value is | |
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 | |
7e2e4b37 NTND |
80 | - Trailing spaces are ignored unless they are quoted with backlash |
81 | ("`\`"). | |
82 | ||
866f5f82 | 83 | - An optional prefix "`!`" which negates the pattern; any |
cedb8d5d | 84 | matching file excluded by a previous pattern will become |
59856de1 KB |
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 | |
2de9b711 | 105 | - Otherwise, Git treats the pattern as a shell glob suitable |
cedb8d5d JT |
106 | for consumption by fnmatch(3) with the FNM_PATHNAME flag: |
107 | wildcards in the pattern will not match a / in the pathname. | |
9257a1ef | 108 | For example, "Documentation/{asterisk}.html" matches |
81c13fde JN |
109 | "Documentation/git.html" but not "Documentation/ppc/ppc.html" |
110 | or "tools/perf/Documentation/perf.html". | |
111 | ||
112 | - A leading slash matches the beginning of the pathname. | |
9257a1ef | 113 | For example, "/{asterisk}.c" matches "cat-file.c" but not |
81c13fde | 114 | "mozilla-sha1/sha1.c". |
cedb8d5d | 115 | |
237ec6e4 NTND |
116 | Two consecutive asterisks ("`**`") in patterns matched against |
117 | full pathname may have special meaning: | |
118 | ||
119 | - A leading "`**`" followed by a slash means match in all | |
120 | directories. For example, "`**/foo`" matches file or directory | |
8447dc89 | 121 | "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`" |
237ec6e4 NTND |
122 | matches file or directory "`bar`" anywhere that is directly |
123 | under directory "`foo`". | |
124 | ||
8447dc89 KB |
125 | - A trailing "`/**`" matches everything inside. For example, |
126 | "`abc/**`" matches all files inside directory "`abc`", relative | |
237ec6e4 NTND |
127 | to the location of the `.gitignore` file, with infinite depth. |
128 | ||
129 | - A slash followed by two consecutive asterisks then a slash | |
130 | matches zero or more directories. For example, "`a/**/b`" | |
131 | matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on. | |
132 | ||
133 | - Other consecutive asterisks are considered invalid. | |
134 | ||
6f02a5a3 JN |
135 | NOTES |
136 | ----- | |
137 | ||
138 | The purpose of gitignore files is to ensure that certain files | |
2de9b711 | 139 | not tracked by Git remain untracked. |
6f02a5a3 JN |
140 | |
141 | To ignore uncommitted changes in a file that is already tracked, | |
142 | use 'git update-index {litdd}assume-unchanged'. | |
143 | ||
144 | To stop tracking a file that is currently tracked, use | |
145 | 'git rm --cached'. | |
146 | ||
0b803a6c JN |
147 | EXAMPLES |
148 | -------- | |
cedb8d5d JT |
149 | |
150 | -------------------------------------------------------------- | |
b1889c36 | 151 | $ git status |
cedb8d5d JT |
152 | [...] |
153 | # Untracked files: | |
154 | [...] | |
155 | # Documentation/foo.html | |
156 | # Documentation/gitignore.html | |
157 | # file.o | |
158 | # lib.a | |
159 | # src/internal.o | |
160 | [...] | |
161 | $ cat .git/info/exclude | |
162 | # ignore objects and archives, anywhere in the tree. | |
163 | *.[oa] | |
164 | $ cat Documentation/.gitignore | |
165 | # ignore generated html files, | |
166 | *.html | |
167 | # except foo.html which is maintained by hand | |
168 | !foo.html | |
b1889c36 | 169 | $ git status |
cedb8d5d JT |
170 | [...] |
171 | # Untracked files: | |
172 | [...] | |
173 | # Documentation/foo.html | |
174 | [...] | |
175 | -------------------------------------------------------------- | |
176 | ||
177 | Another example: | |
178 | ||
179 | -------------------------------------------------------------- | |
180 | $ cat .gitignore | |
181 | vmlinux* | |
182 | $ ls arch/foo/kernel/vm* | |
183 | arch/foo/kernel/vmlinux.lds.S | |
184 | $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore | |
185 | -------------------------------------------------------------- | |
186 | ||
2de9b711 | 187 | The second .gitignore prevents Git from ignoring |
cedb8d5d JT |
188 | `arch/foo/kernel/vmlinux.lds.S`. |
189 | ||
59856de1 KB |
190 | Example to exclude everything except a specific directory `foo/bar` |
191 | (note the `/*` - without the slash, the wildcard would also exclude | |
192 | everything within `foo/bar`): | |
193 | ||
194 | -------------------------------------------------------------- | |
195 | $ cat .gitignore | |
196 | # exclude everything except directory foo/bar | |
197 | /* | |
198 | !/foo | |
199 | /foo/* | |
200 | !/foo/bar | |
201 | -------------------------------------------------------------- | |
202 | ||
6f02a5a3 JN |
203 | SEE ALSO |
204 | -------- | |
368aa529 AS |
205 | linkgit:git-rm[1], |
206 | linkgit:git-update-index[1], | |
207 | linkgit:gitrepository-layout[5], | |
208 | linkgit:git-check-ignore[1] | |
6f02a5a3 | 209 | |
cedb8d5d JT |
210 | GIT |
211 | --- | |
9e1f0a85 | 212 | Part of the linkgit:git[1] suite |