gitignore: document that unignoring a directory unignores everything in it
Also document another limitation coming from a bug in handling the basename match with a directory for 're-inclusion'. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Mar 7, 2016 at 15:27 UTC
6f6d1f41da7271c04923202dda5ece21a543c927
1 file changed
+37
-1
Documentation/gitignore.txt
+37
-1
@@ -148,7 +148,43 @@ excluded, the following conditions must be met:
148
be in the same .gitignore file.
149
150
- The directory part in the re-include rules must be literal (i.e. no
151
- wildcards)
151
+ wildcards and has to start with a `/`).
152
+
153
+A re-inclusion of a directory makes all files in the directory
154
+unignored. For example, suppose you have files `.gitignore`,
155
+`dir/file1`, `dir/file2`, and `dir/file3`, and have the following in
156
+your `.gitignore`:
157
+
158
+----------------
159
+# .gitignore is not mentioned in .gitignore
160
+*
161
+!/dir
162
+# dir/file1 is not mentioned in .gitignore
163
+dir/file2
164
+!dir/file3
165
+----------------
166
+
167
+Then:
168
+
169
+ - `.gitignore` gets ignored, because it matches the `*` at the top
170
+ level;
171
+
172
+ - `dir/file1` does not get ignored, because `/dir` marks everything
173
+ underneath `dir/` directory to be 're-included' unless otherwise
174
+ specified;
175
+
176
+ - `dir/file2` gets ignored, because `dir/file2` matches it.
177
+
178
+ - `dir/file3` does not get ignored, because `!dir/file3` matches it.
179
+ Note that the entry `!dir/file3` is redundant because everything
180
+ underneath `dir/` is marked to be 're-included' already.
181
+
182
+Some earlier versions of Git treated `!/dir` above differently in
183
+that it did not cause the paths under it unignored (but merely told
184
+Git that patterns that begin with dir/ should not be ignored), but
185
+this has been corrected to be consistent with `/dir` that says "the
186
+directory `dir/` and everything below are ignored."
187
+
188
189
EXAMPLES
190
--------