Britton Leo Kerin <britton.kerin@xxxxxxxxx> 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:
