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

It begins:

       For each pathname given via the command-line or from a file via
--stdin, check whether
       the file is excluded by .gitignore (or other input files to the
exclude mechanism) and output
       the path if it is excluded.

In fact it just reports matches from .gitignore etc:

     $ cat .gitignore
     *.o
     !*.dont_ignore
     $ ls
     bar.o.dont_ignore  foo.o
     $ git check-ignore -v -n *
     .gitignore:2:!*.dont_ignore bar.o.dont_ignore
     .gitignore:1:*.o foo.o
     $ # Even more confusing without -v -n:
     $ git check-ignore *
     bar.o.dont_ignore
     foo.o

The EXIT STATUS section is even more wrong:

     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.

but:

     $ if git check-ignore foo.o.dont_ignore; then echo exited true;
else echo exited false; fi
     foo.o.dont_ignore
     exited true
     $

IMO the behavior of git-check-ignore is the correct and useful behavior and the documentation should simply be fixed to reflect the fact that it just lists matching entries rather than wrongly claiming that it returns the overall result of the ignore calculation.

Britton

Hi,

Thanks for the report.

On Tue, Jul 12, 2022 at 4:34 PM Britton Kerin <britton.kerin@gmail.com> wrote:

I suspect we're having an aliasing problem that you're not recognizing. "ignored" and "excluded" are used interchangeably, note that patterns from the $GIT_DIR/info/exclude files and patterns from the file pointed to by core.excludesFile are also lumped together with the patterns from all the .gitignore files (see the gitignore manual page). Further, the internal code refers to them all as "excludes" not as "ignores".

(And then we adopted the same syntax for sparse checkouts, except we used it to mark things that should be included, and we referred everyone to the documentation about "excludes" to learn the format for what to "include". Ugh.)

Yes, it outputs the paths that are excluded, as the documentation said. Perhaps there's a way to reword it to make this clearer? I don't think we can get rid of the alias given the fact that $GIT_DIR/info/exclude and core.excludesFile are hard-coded and must be kept for backward compatibility. But suggestions to improve the wording would be great.

Maybe it'd be as simple as replacing "is excluded" with "matches an ignore/exclude rule"?

"is ignored", meaning "matches an ignore/exclude rule". Perhaps we should update the docs with that textual change?

and replace "are ignored" with the same phrase here?

So the filename matched one of the rules, causing the filename to be printed.

and it returned a 0 exit status, since one of the provided paths was ignored, as documented.

I'm with you here.

Yes, I agree it's easy to misinterpret.  Would my suggested changes help?

I think I understood where the problems were in the documentation that could lead to misinterpretations in the other two cases you mentioned earlier in your email, but I don't understand this one. Even the first sentence you quoted included the phrase that it could "output the path", so I'm not sure where you think it claims that it'd return the overall result of the ignore calculation. Could you point out what in the document led you to believe it was claiming this? Maybe I could suggest wording improvements for it as well. Or maybe you have some.

Elijah Newren <newren@gmail.com> writes:

All true.

I smell a continuation of 7ec8125f (check-ignore: fix documentation and implementation to match, 2020-02-18), which appears in 2.26 and later (the way the negative entries in the ignore/exclude mechanism gets handled has changed in Git 2.26, and the documentation has been updated).

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

Yup, with the old "huh?" fixed in Git 2.26 (which was there simply because check-ignore was not used to be a serious end-user facing program but was more of a debugging aid), I think the behaviour of the command we have today is what we want.

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

Exit status section needs a bit more work. It used to be OK to say "success (0) is returned when we found a path that is ignored", but these days, it is not whether there are ignored paths in the input.

It signals if we found an entry in the list of exclude/ignore patterns that actively affects the path's fate. In our project, if we ask the fate of hello.c

    $ git check-itnore -v hello.c; echo $?
    1

because we do not say explicitly that .c files are usually tracked sources. If we did this:

    $ echo >>.git/info/exclude '!*.c'

to explicitly say that .c files are never ignored, it changes the picture:

    $ git check-itnore -v hello.c; echo $?
    .git/info/exclude:15:!*.c	hello.c
    0

Junio C Hamano <gitster@pobox.com> writes:

I wasn't surprised that 'ignoread' and 'excluded' are used interchangably, that's not the problem.

I think replacing with "matches an ignore/exclude rule" is prefereable since that's what's actually going on. It's still a bit unfortunate since the ignore/exclude terms are potentially confusing in the presence of dont-ignore (!) rules, but it seems likely that people running check-ignore are looking to sort out something complicated and are probably aware of negative rules, and anyway they get a ! to clue them in :)

Adding some explanation to the first use of "excluded" would in principle solve the problem by itself and give licence to use the term however you want, but to be honest I'm not sure I would have read that paragraph carefully enough to get the idea. It still seems better to me to use different language each time it comes up in the page.

Good point: it's not exactly a full query either.

If it would be welcome and hasn't already been done I could rewrite this page to be clearer without adding or changing much.

Britton

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

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:

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(-)