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

[Junio C Hamano <gitster@pobox.com>]

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".

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.

>> Signed-off-by: Karsten Blees <blees@dcon.de>
>> ---
>>  Documentation/gitignore.txt | 18 ++++++++++++++++--
>>  1 file changed, 16 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
>> index f971960..5ecc48e 100644
>> --- a/Documentation/gitignore.txt
>> +++ b/Documentation/gitignore.txt
>> @@ -79,8 +79,9 @@ PATTERN FORMAT
>>  
>>   - 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`".
>>  
>> @@ -182,6 +183,19 @@ Another example:
>>  The second .gitignore prevents Git from ignoring
>>  `arch/foo/kernel/vmlinux.lds.S`.
>>  
>> +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
>> +--------------------------------------------------------------
>> +
>>  SEE ALSO
>>  --------
>>  linkgit:git-rm[1],