git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Britton Leo Kerin <britton.kerin@gmail.com>
To: gitster@pobox.com
Cc: britton.kerin@gmail.com, git@vger.kernel.org, newren@gmail.com
Subject: Re: BUG: git-check-ignore documentation doesn't come close to describing what it really does
Date: Mon, 18 Jul 2022 15:28:43 -0800	[thread overview]
Message-ID: <20220718232843.151392-1-britton.kerin@gmail.com> (raw)
In-Reply-To: <xmqqtu7lc587.fsf@gitster.g>

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

> Elijah Newren <newren@gmail.com> writes:
>
> > 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.

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

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

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.

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

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

  reply	other threads:[~2022-07-18 23:28 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-07-12 23:02 BUG: git-check-ignore documentation doesn't come close to describing what it really does Britton Kerin
2022-07-13  0:17 ` Elijah Newren
2022-07-13 17:06   ` Junio C Hamano
2022-07-18 23:28     ` Britton Leo Kerin [this message]
2022-07-19  6:27       ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220718232843.151392-1-britton.kerin@gmail.com \
    --to=britton.kerin@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=newren@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).