[thirdparty/git.git] / Documentation / git-check-ignore.txt

git-check-ignore(1)
===================

NAME
----
git-check-ignore - Debug gitignore / exclude files


SYNOPSIS
--------
[verse]
'git check-ignore' [<options>] <pathname>...
'git check-ignore' [<options>] --stdin

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
input files to the exclude mechanism) and output the path if it is
excluded.

By default, tracked files are not shown at all since they are not
subject to exclude rules; but see `--no-index'.

OPTIONS
-------
-q, --quiet::
	Don't output anything, just set exit status.  This is only
	valid with a single pathname.

-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
	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.)
+
For precedence rules within and between exclude sources, see
linkgit:gitignore[5].

--stdin::
	Read pathnames from the standard input, one per line,
	instead of from the command-line.

-z::
	The output format is modified to be machine-parsable (see
	below).  If `--stdin` is also given, input paths are separated
	with a NUL character instead of a linefeed character.

-n, --non-matching::
	Show given paths which don't match any pattern.	 This only
	makes sense when `--verbose` is enabled, otherwise it would
	not be possible to distinguish between paths which match a
	pattern and those which don't.

--no-index::
	Don't look in the index when undertaking the checks. This can
	be used to debug why a path became tracked by e.g. `git add .`
	and was not ignored by the rules as expected by the user or when
	developing patterns including negation to match a path previously
	added with `git add -f`.

OUTPUT
------

By default, any of the given pathnames which match an ignore pattern
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.

If `--verbose` is specified, the output is a series of lines of the form:

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

<pathname> is the path of a file being queried, <pattern> is the
matching pattern, <source> is the pattern's source file, and <linenum>
is the line number of the pattern within that source.  If the pattern
contained a `!` prefix or `/` suffix, it will be preserved in the
output.  <source> will be an absolute path when referring to the file
configured by `core.excludesFile`, or relative to the repository root
when referring to `.git/info/exclude` or a per-directory exclude file.

If `-z` is specified, the pathnames in the output are delimited by the
null character; if `--verbose` is also specified then null characters
are also used instead of colons and hard tabs:

<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>

If `-n` or `--non-matching` are specified, non-matching pathnames will
also be output, in which case all fields in each output record except
for <pathname> will be empty.  This can be useful when running
non-interactively, so that files can be incrementally streamed to
STDIN of a long-running check-ignore process, and for each of these
files, STDOUT will indicate whether that file matched a pattern or
not.  (Without this option, it would be impossible to tell whether the
absence of output for a given file meant that it didn't match any
pattern, or that the output hadn't been generated yet.)

Buffering happens as documented under the `GIT_FLUSH` option in
linkgit:git[1].  The caller is responsible for avoiding deadlocks
caused by overfilling an input buffer or reading from an empty output
buffer.

EXIT STATUS
-----------

0::
	One or more of the provided paths is ignored.

1::
	None of the provided paths are ignored.

128::
	A fatal error was encountered.

SEE ALSO
--------
linkgit:gitignore[5]
linkgit:git-config[1]
linkgit:git-ls-files[1]

GIT
---
Part of the linkgit:git[1] suite
Commit	Line	Data
	1	git-check-ignore(1)
	2	===================
	3
	4	NAME
	5	----
	6	git-check-ignore - Debug gitignore / exclude files
	7
	8
	9	SYNOPSIS
	10	--------
	11	[verse]
	12	'git check-ignore' [<options>] <pathname>...
	13	'git check-ignore' [<options>] --stdin
	14
	15	DESCRIPTION
	16	-----------
	17
	18	For each pathname given via the command-line or from a file via
	19	`--stdin`, check whether the file is excluded by .gitignore (or other
	20	input files to the exclude mechanism) and output the path if it is
	21	excluded.
	22
	23	By default, tracked files are not shown at all since they are not
	24	subject to exclude rules; but see `--no-index'.
	25
	26	OPTIONS
	27	-------
	28	-q, --quiet::
	29	Don't output anything, just set exit status. This is only
	30	valid with a single pathname.
	31
	32	-v, --verbose::
	33	Instead of printing the paths that are excluded, for each path
	34	that matches an exclude pattern, print the exclude pattern
	35	together with the path. (Matching an exclude pattern usually
	36	means the path is excluded, but if the pattern begins with '!'
	37	then it is a negated pattern and matching it means the path is
	38	NOT excluded.)
	39	+
	40	For precedence rules within and between exclude sources, see
	41	linkgit:gitignore[5].
	42
	43	--stdin::
	44	Read pathnames from the standard input, one per line,
	45	instead of from the command-line.
	46
	47	-z::
	48	The output format is modified to be machine-parsable (see
	49	below). If `--stdin` is also given, input paths are separated
	50	with a NUL character instead of a linefeed character.
	51
	52	-n, --non-matching::
	53	Show given paths which don't match any pattern. This only
	54	makes sense when `--verbose` is enabled, otherwise it would
	55	not be possible to distinguish between paths which match a
	56	pattern and those which don't.
	57
	58	--no-index::
	59	Don't look in the index when undertaking the checks. This can
	60	be used to debug why a path became tracked by e.g. `git add .`
	61	and was not ignored by the rules as expected by the user or when
	62	developing patterns including negation to match a path previously
	63	added with `git add -f`.
	64
	65	OUTPUT
	66	------
	67
	68	By default, any of the given pathnames which match an ignore pattern
	69	will be output, one per line. If no pattern matches a given path,
	70	nothing will be output for that path; this means that path will not be
	71	ignored.
	72
	73	If `--verbose` is specified, the output is a series of lines of the form:
	74
	75	<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>
	76
	77	<pathname> is the path of a file being queried, <pattern> is the
	78	matching pattern, <source> is the pattern's source file, and <linenum>
	79	is the line number of the pattern within that source. If the pattern
	80	contained a `!` prefix or `/` suffix, it will be preserved in the
	81	output. <source> will be an absolute path when referring to the file
	82	configured by `core.excludesFile`, or relative to the repository root
	83	when referring to `.git/info/exclude` or a per-directory exclude file.
	84
	85	If `-z` is specified, the pathnames in the output are delimited by the
	86	null character; if `--verbose` is also specified then null characters
	87	are also used instead of colons and hard tabs:
	88
	89	<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>
	90
	91	If `-n` or `--non-matching` are specified, non-matching pathnames will
	92	also be output, in which case all fields in each output record except
	93	for <pathname> will be empty. This can be useful when running
	94	non-interactively, so that files can be incrementally streamed to
	95	STDIN of a long-running check-ignore process, and for each of these
	96	files, STDOUT will indicate whether that file matched a pattern or
	97	not. (Without this option, it would be impossible to tell whether the
	98	absence of output for a given file meant that it didn't match any
	99	pattern, or that the output hadn't been generated yet.)
	100
	101	Buffering happens as documented under the `GIT_FLUSH` option in
	102	linkgit:git[1]. The caller is responsible for avoiding deadlocks
	103	caused by overfilling an input buffer or reading from an empty output
	104	buffer.
	105
	106	EXIT STATUS
	107	-----------
	108
	109	0::
	110	One or more of the provided paths is ignored.
	111
	112	1::
	113	None of the provided paths are ignored.
	114
	115	128::
	116	A fatal error was encountered.
	117
	118	SEE ALSO
	119	--------
	120	linkgit:gitignore[5]
	121	linkgit:git-config[1]
	122	linkgit:git-ls-files[1]
	123
	124	GIT
	125	---
	126	Part of the linkgit:git[1] suite