Adam Spiers <git@xxxxxxxxxxxxxx> writes:
> +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.
> +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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html