[PATCH] git-check-ignore.txt: Clarify exit codes

[PATCH] git-check-ignore.txt: Clarify exit codes

[Florian Hassanen]

check-ignore disregards whether a path is matched by a
positive or negative pattern. Thus for a file that is _not_
ignored, but is captured by negative pattern in .gitignore,
the exit code is 0. The docs suggested otherwise.

Clarify docs to explain that only the match matters, not
whether the path is actually ignored or not.

Signed-off-by: Florian Hassanen <florian.hassanen@gmail.com>
---
Today when working with the check-ignore command, I misunderstood
the docs into thinking, that I could use check-ignore's exit code
to determine, whether a file is ignored or not - but this is not
how the exit code works :(
Here is a suggestion, on how to update the docs to describe the 
exit code's behavior more clearly.

 Documentation/git-check-ignore.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index ee2e091..bdd8b7c 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -97,10 +97,11 @@ EXIT STATUS
 -----------
 
 0::
-	One or more of the provided paths is ignored.
+	At least one of the provided paths matches some (possibly negative)
+	pattern.
 
 1::
-	None of the provided paths are ignored.
+	None of the provided paths match any pattern.
 
 128::
 	A fatal error was encountered.
-- 
2.1.3

Re: [PATCH] git-check-ignore.txt: Clarify exit codes

[Junio C Hamano]

Florian Hassanen <florian.hassanen@gmail.com> writes:

> check-ignore disregards whether a path is matched by a
> positive or negative pattern. Thus for a file that is _not_
> ignored, but is captured by negative pattern in .gitignore,
> the exit code is 0. The docs suggested otherwise.

I am not sure that is the actual behaviour of the command.  Given
this .gitignore file:

    $ cat .gitignore; echo END
    !vendor.o
    *.o
    END

which is designed to allow binary-only blob "vendor.o" supplied by
the vendor to be tracked, but to ignore all the other usual build
artifacts, you see this:

    $ for o in a.o vendor.o; do git check-ignore $o >/dev/null; echo $?; done
    0
    1

Puzzled...

>
> Clarify docs to explain that only the match matters, not
> whether the path is actually ignored or not.
>
> Signed-off-by: Florian Hassanen <florian.hassanen@gmail.com>
> ---
> Today when working with the check-ignore command, I misunderstood
> the docs into thinking, that I could use check-ignore's exit code
> to determine, whether a file is ignored or not - but this is not
> how the exit code works :(
> Here is a suggestion, on how to update the docs to describe the 
> exit code's behavior more clearly.
>
>  Documentation/git-check-ignore.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
> index ee2e091..bdd8b7c 100644
> --- a/Documentation/git-check-ignore.txt
> +++ b/Documentation/git-check-ignore.txt
> @@ -97,10 +97,11 @@ EXIT STATUS
>  -----------
>  
>  0::
> -	One or more of the provided paths is ignored.
> +	At least one of the provided paths matches some (possibly negative)
> +	pattern.
>  
>  1::
> -	None of the provided paths are ignored.
> +	None of the provided paths match any pattern.
>  
>  128::
>  	A fatal error was encountered.

Re: [PATCH] git-check-ignore.txt: Clarify exit codes

[Florian Hassanen]

>> check-ignore disregards whether a path is matched by a
>> positive or negative pattern. Thus for a file that is _not_
>> ignored, but is captured by negative pattern in .gitignore,
>> the exit code is 0. The docs suggested otherwise.
>
> I am not sure that is the actual behaviour of the command.  Given
> this .gitignore file:
>
>     $ cat .gitignore; echo END
>     !vendor.o
>     *.o
>     END
>
> which is designed to allow binary-only blob "vendor.o" supplied by
> the vendor to be tracked, but to ignore all the other usual build
> artifacts, you see this:
>
>     $ for o in a.o vendor.o; do git check-ignore $o >/dev/null; echo $?; done
>     0
>     1
>
> Puzzled...

Maybe your global ignore file gets in the way?

on both of my machines (cygwin + git 2.1.1, linux + git @master) I have:

  $ cat > .gitignore << EOF
  !vendor.o
  *.o
  EOF

  for o in a.o vendor.o; do git check-ignore $o >/dev/null; echo $?; done
  0
  0

which corresponds to how I understand the command so far :)

is one of a.o and vendor.o already in your index?
there is a --no-index as well (which enables yet another different behavior)

Re: [PATCH] git-check-ignore.txt: Clarify exit codes

[Junio C Hamano]

Florian Hassanen <florian.hassanen@gmail.com> writes:

> Maybe your global ignore file gets in the way?

No, as I do not have one.

> is one of a.o and vendor.o already in your index?

Bingo.  I did "git add ." to see if the .gitignore file is doing the
right thing before running that demonstration.

It smells like you spotted a bug in the behaviour, not a bug in the
documentation, at least to me.

Re: [PATCH] git-check-ignore.txt: Clarify exit codes

[Florian Hassanen]

> It smells like you spotted a bug in the behaviour, not a bug in the
> documentation, at least to me.

At first I thought so as well :-)
I even prepared a patch, just to find out, that existing tests specifically
test for this "unintuitive" behavior.

Then I read the docs in more detail and found this:

  If the pattern contained a ! prefix or / suffix, it will be
preserved in the output.

So it seems there is indeed the intent to output patterns, even if
they are negated/negative.

Another problem I see with providing "correct" behavior is this:

If I do a test for a non existant file, it cannot be decided whether I
mean a file or a directory.

e.g.

having a gitignore with a single line

  dir/

which only ignores die _directory_ dir, but not the _file_ dir

the exit code for

  $ git check-ignore dir

could either be 0 or 1, depending on whether a _file_ named "dir" or a
_directory_
named "dir" was meant.

I assume that the command is meant to get the applying entry of the gitignore
and then its up to the consumer to provide additional logic to determine whether
the path is actually ignored or not.

I am not sure what the correct behavior should be. And whether some
code already depends
on this command.

My personal preference, would be a behavior like

$ # regardless whether dir exists or not
$ git check-ignore dir # a file is meant
$ git check-ignore dir/ # a directory is mean

and the exit code should only depend on whether the file is actually
ignored or not
- and not if there is an arbitrary matching pattern in gitignore

PS: btw, the previously discussed gitignore file should have read
(note the order)
cat > .gitignore << EOF
*.o
!vendor.o
EOF

because always the last matching entry applies
(so exceptions must come last) - but the exit codes are still the same

On Fri, Dec 12, 2014 at 12:21 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Florian Hassanen <florian.hassanen@gmail.com> writes:
>
>> Maybe your global ignore file gets in the way?
>
> No, as I do not have one.
>
>> is one of a.o and vendor.o already in your index?
>
> Bingo.  I did "git add ." to see if the .gitignore file is doing the
> right thing before running that demonstration.
>
> It smells like you spotted a bug in the behaviour, not a bug in the
> documentation, at least to me.
>