Re: [PATCH 2/2] gitignore.txt: clarify recursive nature of excluded directories

[Karsten Blees <karsten.blees@gmail.com>]

Am 07.11.2013 20:55, schrieb Jeff King:
> On Thu, Nov 07, 2013 at 11:37:38AM -0800, Junio C Hamano wrote:
> 
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> Karsten Blees <karsten.blees@gmail.com> writes:
>>>
>>>> Additionally, precedence of negated patterns is exactly as outlined in
>>>> the DESCRIPTION section, we don't need to repeat this.
>>>
>>> Very good, thanks.
>>>
>>> Even though I have a suspicion that somebody else may be able to
>>> come up with a better phrase that does not sound unnecessarily
>>> strongly than "recursively and irrevocably", that somebody else is
>>> not me, so I'll queue this as-is for now.
>>
>> Just in case somebody thinks about rephrasing, to me, these two
>> words sound heavier than the information they actually convey, and
>> that is why I said "unnecessarily strong".
> 
> I agree that it seems unnecessarily strong.  The word "irrevocable" to
> me implies that it cannot ever be changed. But of course it is only
> irrevocable for the particular run; you can always edit the .gitignore
> file. :)
> 
>> The key thing in the behaviour when a directory is excluded is that
>> it tells us to stop going into that directory, and there is no way
>> to override it with another .gitignore file somewhere inside,
>> because we are told not to even bother looking for it.  "Recursively
>> and irrevocably" may be an accurate description of the end result,
>> but that sounds more like a rule without a "because"; to a reader
>> (me), it lacks the "aha, of course" that comes from understanding
>> why.
> 
> I think it is more than just "we do not descend and so do not read the
> .gitignore file". I thought the previous discussion on this topic showed
> that you cannot do:
> 
>   $ cat .gitignore
>   foo
>   !foo/bar
> 
> to see foo/bar.
>

Yes, the pattern could be in .git/info/exclude and it still wouldn't work.
 
>>>>   - An optional prefix "`!`" which negates the pattern; any
>>>>     matching file excluded by a previous pattern will become
>>>> -   included again.  If a negated pattern matches, this will
>>>> -   override lower precedence patterns sources.
>>>> +   included again. It is not possible to re-include a file if a parent
>>>> +   directory of that file is excluded (i.e. excluding a directory
>>>> +   will recursively and irrevocably exclude the entire content).
>>>>     Put a backslash ("`\`") in front of the first "`!`" for patterns
>>>>     that begin with a literal "`!`", for example, "`\!important!.txt`".
> 
> How about:
> 
>   It is not possible to re-include a file if a parent directory of that
>   file is excluded. Once git considers a directory excluded, it does not
>   descend into the directory to consider its contents further.
> 

Hmm...an unsuspecting reader might still assume that it works in top-level .gitignore, given the precendence rules above...

How about this:

   It is not possible to re-include a file if a parent directory of that
   file is excluded. Git doesn't list excluded directories for performance
   reasons, so any patterns on contained files have no effect, no matter
   where they are defined.

>>>> +Example to exclude everything except a specific directory `foo/bar`
>>>> +(note the `/*` - without the slash, the wildcard would also exclude
>>>> +everything within `foo/bar`):
>>>> +
>>>> +--------------------------------------------------------------
>>>> +    $ cat .gitignore
>>>> +    # exclude everything except directory foo/bar
>>>> +    /*
>>>> +    !/foo
>>>> +    /foo/*
>>>> +    !/foo/bar
>>>> +--------------------------------------------------------------
> 
> That looks good to me. The simplest example would be handling a
> top-level directory (i.e., ignore all except `/foo`). That is a subset
> of what's happening above, and I think showing the general case is good.
> I'd worry slightly that a non-astute reader might not figure out how to
> simplify down to the top-level case, and we should have two examples. I
> may just be overly pessimistic, though.
> 
> -Peff
>