Re: BUG: git-check-ignore documentation doesn't come close to describing what it really does

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

Britton Leo Kerin <britton.kerin@gmail.com> writes:

>> "Is excluded" is perfectly fine, I think.  The first use of that
>> verb in the documentation should be a bit more careful, e.g. "is
>> excluded (aka ignored)" or something.
>
> I think replacing with "matches an ignore/exclude rule" is prefereable since
> that's what's actually going on.

Unfortunately, it is only half of what's actually going on, isn't
it?  If the last match is with a positive entry, then it is excluded
(aka ignored).  If the last match is with a negative entry, then it
is not excluded (and not shown without "-v").  That is demonstrated
by the example:

>> It does return *the* matching entry that decided the path's fate.
>>
>>     $ (echo '/no-such-*'; echo '!/no-such-*') >>.git/info/exclude
>>     $ git check-ignore -v no-such-directory; echo $?
>>     .git/info/exclude:14:!/no-such-*	no-such-directory
>>     0

and

    $ git check-ignore no-such-directory; echo $?
    1

i.e. with "-v", the output can give enough clue to the user if the
match was with positive or negative entry, but without "-v", the
exit status reports if the given path is "excluded (aka ignored)".
In the above case, the last entry that matches the path
"no-such-directory" is a negative entry, so the path is not
excluded, hence there is no output (as documented, excluded paths
are output).

If we remove the last line from .git/info/exclude, then the
transcript would become:

    $ git check-ignore no-such-directory; echo $?
    no-such-directory
    0
    $ git check-ignore -v no-such-directory; echo $?
    .git/info/exclude:13:/no-such-* no-such-directory
    0

As the last entry that matches the path is a positive entry in this
case, the path is excluded and it is shown in the output without
"-v" and the command exits with success (i.e. is excluded).

Here is a rough attempt to clarify what I found was unclear in the
current documentation.

Thanks.

 Documentation/git-check-ignore.txt | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git c/Documentation/git-check-ignore.txt w/Documentation/git-check-ignore.txt
index 2892799e32..a5491386cf 100644
--- c/Documentation/git-check-ignore.txt
+++ w/Documentation/git-check-ignore.txt
@@ -16,7 +16,8 @@ DESCRIPTION
 -----------
 
 For each pathname given via the command-line or from a file via
-`--stdin`, check whether the file is excluded by .gitignore (or other
+`--stdin`, check whether the file is excluded (aka "ignored"---these
+words are used interchangeably) by .gitignore (or other
 input files to the exclude mechanism) and output the path if it is
 excluded.
 
@@ -31,11 +32,12 @@ OPTIONS
 
 -v, --verbose::
 	Instead of printing the paths that are excluded, for each path
-	that matches an exclude pattern, print the exclude pattern
-	together with the path.  (Matching an exclude pattern usually
+	that matches an exclude pattern (or more), print the exclude
+	pattern that decides if the path is excluded or not excluded,
+	together with the path.  Matching an exclude pattern usually
 	means the path is excluded, but if the pattern begins with "`!`"
 	then it is a negated pattern and matching it means the path is
-	NOT excluded.)
+	NOT excluded.
 +
 For precedence rules within and between exclude sources, see
 linkgit:gitignore[5].
@@ -65,10 +67,12 @@ linkgit:gitignore[5].
 OUTPUT
 ------
 
-By default, any of the given pathnames which match an ignore pattern
+By default, any of the given pathnames which are excluded (aka ignored)
 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.
+ignored.  If the pattern that matched the path is a negative one (i.e.
+prefixed with "`!`"), the path is not excluded and nothing is output
+for the path.
 
 If `--verbose` is specified, the output is a series of lines of the form: