patchgit-check-ignore.txt: Clarify exit codes

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(-)

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

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)

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

No, as I do not have one.

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.

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: