Re: [PATCH 9/9] Add git-check-ignores

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 2, 2012, 20:41 UTC
Message-ID: <7vvcfwf937.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1346544731-938-10-git-send-email-git@adamspiers.org>

Adam Spiers <git@adamspiers.org> writes:

Show 8 quoted lines

> +OPTIONS
> +-------
> +--stdin::
> +	Read file names from stdin instead of from the command-line.
> +
> +-z::
> +	Only meaningful with `--stdin`; paths are separated with a
> +	NUL character instead of a linefeed character.

On input, or on output, or both?

The answer should be "both", otherwise you cannot safely handle paths with funny character in your script, even if you wanted to. Which means that this cannot only be meaningful with "--stdin", I think.

Show 12 quoted lines

> +OUTPUT
> +------
> +
> +The output is a series of lines of the form:
> +
> +<path> COLON SP <type> SP <pattern> SP <source> SP <position> LF
> +
> +<path> is the path of a file being queried, <type> is either
> +'excluded' or 'included' (for patterns prefixed with '!'), <pattern>
> +is the matching pattern, <source> is the pattern's source file (either
> +as an absolute path or relative to the repository root), and
> +<position> is the position of the pattern within that source.

Let's step back a bit and think what this command is about. What is the reason why the user wants to run "check-ignore $path" in the first place? I think there are two (or three, depending on how you count).

 (1) You have one (or more) paths at hand.  You want to know if it
     is (or some of them are) ignored, but you do not particularly
     care how they are ignored.  Think of implementing your own "git
     add" as a script.

 (2) You have one or more paths that are ignored but do not want
     them to be, and want to find out why they are.

For the former, your script may want to see the paths sifted into "ignored" bin and "not-ignored" bin, so

	git check-ignore [-z] --name-only $paths

that gives you only the paths without any reason is more useful. You also may want the opposite (show only paths not ignored), but that can be computed easily by the script, so it is of lessor importance.

For the latter, you are debugging the set of exclude sources and want to learn where the decision to exclude it comes from. For that kind of use, it would be more useful if the output mimicked error messages from the compilers and output from "grep -n" to show the source, e.g.

	.gitignore:13:/git-am	git-am

Emacs users can use "M-x grep<RET>git check-ignore -v git-am<RET>", see the output, and find the hit in its output (I would imagine vim would have a similar feature). The output format would be something like:

	<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>

I do not think you need excluded/included <type> as a separate item in the non "-z" output, as it should be clear from the <pattern>. Substitute "<cmdline>" (literally) as source for patterns obtained from the command line.

I would also suggest to

 (1) make --name-only the default (i.e. no need to have the
     "--name-only" option);

 (2) give the version that mimicks "grep -n" when "-v|--verbose" is
     given; and

 (3) support "--quiet"; the command would exit with status 0 if
     _any_ of the paths given is ignored, or status 1 if none of the
     paths is ignored (or error out with die() when --quiet and
     multiple paths are given).

Regarding "-z" (for script consumption), I do not object to the broken down format, e.g., "check-ignore -z -v" may give a sequence of

    <pathname> NUL <type> NUL <pattern> NUL <source> NUL <position> NUL

while "check-ignore -z" would give a sequence of

    <pathname> NUL