Re: Change in .gitignore handling: intended or bug?

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 8, 2016, 18:10 UTC
Message-ID: <xmqqbn6olu1w.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CACsJy8C5r2f76p3oq5oX_1P5Vqt9qd7TAafuKxJ=Y8baELbJog@mail.gmail.com>

Duy Nguyen <pclouds@gmail.com> writes:

Show 29 quoted lines

> On Tue, Mar 8, 2016 at 1:14 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> We need documentation update to settle this one before 2.8 final
>>> ships, as we seem to be seeing more and more end-user confusion on
>>> the list.  I tried to come up with a trimmed-down example, which is
>>> shown below, but I suspect that the code is not exactly working the
>>> way it is described in that (1) dir/file1 is ignored and (3)
>>> !dir/file3 entry makes difference.
>>>
>>> Where did my example go wrong?
>>>
>>> FYI, if I prefix '/' to all the .gitignore entries in the example, i.e.
>>> making it
>>>
>>>     *
>>>     !/dir
>>>     /dir/file2
>>>     !/dir/file3
>>>
>>> instead, then dir/file1 and dir/file3 do get shown as unignored.
>
> Arghhh.. bug!!!
>
> The difference between "dir" and "/dir" is, the former is basename
> matching while the latter is pathname matching. When we check
> dir/file1 after we enter "dir", we do try to check rule "!/dir" (or
> "!dir") before rule "*". In the pathname matching case, it works
> thanks to a60ea8f.

So what do we want to do for the upcoming release? I am OK to leave the code as-is for now and describe it as a known bug that is still being worked on (as long as it indeed is being worked on, that is), as the desired endgame of making "!dir" act in a way more similar to how "dir" acts does sound sensible.

If we are going that route, perhaps something like this is the minimum we would need before 2.8 final.

Thoughts?

 Documentation/gitignore.txt | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 3ded6fd..91d1ce2 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -148,7 +148,43 @@ excluded, the following conditions must be met:
    be in the same .gitignore file.
 
  - The directory part in the re-include rules must be literal (i.e. no
-   wildcards)
+   wildcards and has to start with a `/`).
+
+A re-inclusion of a directory makes all files in the directory
+unignored.  For example, suppose you have files `.gitignore`,
+`dir/file1`, `dir/file2`, and `dir/file3`, and have the following in
+your `.gitignore`:
+
+----------------
+# .gitignore is not mentioned in .gitignore
+*
+!/dir
+# dir/file1 is not mentioned in .gitignore
+dir/file2
+!dir/file3
+----------------
+
+Then:
+
+ - `.gitignore` gets ignored, because it matches the `*` at the top
+   level;
+
+ - `dir/file1` does not get ignored, because `/dir` marks everything
+   underneath `dir/` directory to be 're-included' unless otherwise
+   specified;
+
+ - `dir/file2` gets ignored, because `dir/file2` matches it.
+
+ - `dir/file3` does not get ignored, because `!dir/file3` matches it.
+   Note that the entry `!dir/file3` is redundant because everything
+   underneath `dir/` is marked to be 're-included' already.
+
+Some earlier versions of Git treated `!/dir` above differently in
+that it did not cause the paths under it unignored (but merely told
+Git that patterns that begin with dir/ should not be ignored), but
+this has been corrected to be consistent with `/dir` that says "the
+directory `dir/` and everything below are ignored."
+
 
 EXAMPLES
 --------