Subject: Re: bug:git-check-ignore exit status is wrong for negative patterns when -v option used

From: Junio C Hamano <[email-masked]>
Date: Fri, 30 Apr 2021 09:22:20 +0900

Jeremy Faith <[email-masked]> writes:

> man git-check-ignore states:-
> EXIT STATUS
> -----------
> 0::
> 	One or more of the provided paths is ignored.
> 1::
> 	None of the provided paths are ignored.
> 128::
> 	A fatal error was encountered.
>
> So my change matches what the manual states.

That is part of what I meant by "understandable, given the history".

The above description is _wrong_ ever since it was introduced, along
with check-ignore, at 368aa529 (add git-check-ignore sub-command,
2013-01-06).  It should have said "has/have entry that affects it in
the gitignore/exclude files" instead of "is/are ignored".  After
all, that is what the tool was written to do, i.e. to help debugging
the gitignore/exclude files.

    git-check-ignore(1)
    ===================

    NAME
    ----
    git-check-ignore - Debug gitignore / exclude files

Having said all that.

It is a misunderstanding that check-ignore is a tool to learn if a
path is or is not ignored, but the misunderstanding is so widespread.

I wonder if we can repurpose the command to "match" the
misunderstanding, without hurting existing users, by

 (1) updating the one-liner description of the command in the
     documentation;

 (2) keep the EXIT STATUS section as-is; and

 (3) adjust the code to exit with status that reflects if there was
     at least one path that was ignored (not "that had an entry in
     the gitignore/exclude files that affected its fate").

That certainly is a backward compatible change, but I suspect that
we may be able to sell it as a bugfix, taking advantage of the
documentation bug you quoted above.  Of course, people do not read
documentation, so scripts that used to use the command in the way it
was intended to be used (as opposed to "the way it was documented")
will still get broken with such a change, though.