From: Junio C Hamano <gitster@pobox.com>
To: Britton Leo Kerin <britton.kerin@gmail.com>
Cc: 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 23:27:21 -0700 [thread overview]
Message-ID: <xmqqa695ehx2.fsf@gitster.g> (raw)
In-Reply-To: <20220718232843.151392-1-britton.kerin@gmail.com> (Britton Leo Kerin's message of "Mon, 18 Jul 2022 15:28:43 -0800")
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:
prev parent reply other threads:[~2022-07-19 6:27 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
2022-07-19 6:27 ` Junio C Hamano [this message]
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=xmqqa695ehx2.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=britton.kerin@gmail.com \
--cc=git@vger.kernel.org \
--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).