From: Adam Spiers <git@adamspiers.org>
Date: Tue, 16 Oct 2012 14:13:46 GMT
Subject: Re: [PATCH 12/12] Add git-check-ignore sub-command
Message-ID: <CAOkDyE9g6rNiv7nnTu2i34dbn_z7r5SmhDuxief7iEQLVxtO5g@mail.gmail.com>
In-Reply-To: <7vlif7v03r.fsf@alter.siamese.dyndns.org>

On Mon, Oct 15, 2012 at 3:31 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:
>
>> +For each pathname given via the command-line or from a file via
>> +`--stdin`, this command will list the first exclude pattern found (if
>> +any) which explicitly excludes or includes that pathname.  Note that
>> +within any given exclude file, later patterns take precedence over
>> +earlier ones, so any matching pattern which this command outputs may
>> +not be the one you would immediately expect.
>
> "The first exclude pattern" is very misleading, isn't it?

I don't think so, because of the second sentence.

> For example, with these in $GIT_DIR/info/exclude, I would get:
>
>         $ cat -n .git/info/exclude
>           1 *~
>           2 Makefile~
>         $ git check-ignore -v Makefile~
>         .git/info/exclude:2:Makefile~   Makefile~
>
> which is the correct result (the last one in a single source decides
> the fate of the path), but it hardly is "first one found" and the
> matching pattern in the output would not be something unexpected for
> the users, either.
>
> The reason it is "the first one found" is because the implementation
> arranges the loop in such a way that it can stop early when it finds
> a match---it simply checks matches from the end of the source.
>
> But that is not visible to end-users,

Correct; that's precisely why I wrote the second sentence which
explicitly explains this.

> and they will find the above description just wrong, no?

It's not wrong AFAICS, but suggestions for rewording this more clearly
are of course welcome.  Maybe s/immediately/intuitively/ ?

>> +OUTPUT
>> +------
>> +
>> +By default, any of the given pathnames which match an ignore pattern
>> +will be output, one per line.  If no pattern matches a given path,
>> +nothing will be output for that path; this means that path will not be
>> +ignored.
>> +
>> +If `--verbose` is specified, the output is a series of lines of the form:
>> +
>> +<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>
>> +
>> +<pathname> is the path of a file being queried, <pattern> is the
>> +matching pattern, <source> is the pattern's source file, and <linenum>
>> +is the line number of the pattern within that source.  If the pattern
>> +contained a `!` prefix or `/` suffix, it will be preserved in the
>> +output.  <source> will be an absolute path when referring to the file
>> +configured by `core.excludesfile`, or relative to the repository root
>> +when referring to `.git/info/exclude` or a per-directory exclude file.
>> +
>> +If `-z` is specified, the output is a series of lines of the form:
>> +
>
> Hmph... the remainder of the paragraph seems to have been chopped off.

Yes, an earlier review also caught this but I have not had time to fix
it yet, sorry :-/