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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 13, 2022, 17:06 UTC
Message-ID: <xmqqtu7lc587.fsf@gitster.g>
In-Reply-To: <CABPp-BG5qjp9Rx+=CCeLMiOH2Bqpa3kmBWRWdu7fTtPM-H=3kA@mail.gmail.com>

Elijah Newren <newren@gmail.com> writes:

Show 7 quoted lines

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

All true.

Show 9 quoted lines

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

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.

>> IMO the behavior of git-check-ignore is the correct and useful
>> behavior
>
> I'm with you here.

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.

Show 17 quoted lines

>> and the documentation should simply be fixed
>
> Yes, I agree it's easy to misinterpret.  Would my suggested changes help?
>
>> to reflect the
>> fact that it just lists matching entries rather than wrongly claiming
>> that it returns the overall result of the ignore calculation.
>
> 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.

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