611754f10bb86d62edcb3265cc29ccdc97c259ae
[git/git.git] / Documentation / git-check-ignore.txt
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 Also output details about the matching pattern (if any)
34 for each given pathname. For precedence rules within and
35 between exclude sources, see linkgit:gitignore[5].
36
37 --stdin::
38 Read pathnames from the standard input, one per line,
39 instead of from the command-line.
40
41 -z::
42 The output format is modified to be machine-parseable (see
43 below). If `--stdin` is also given, input paths are separated
44 with a NUL character instead of a linefeed character.
45
46 -n, --non-matching::
47 Show given paths which don't match any pattern. This only
48 makes sense when `--verbose` is enabled, otherwise it would
49 not be possible to distinguish between paths which match a
50 pattern and those which don't.
51
52 --no-index::
53 Don't look in the index when undertaking the checks. This can
54 be used to debug why a path became tracked by e.g. `git add .`
55 and was not ignored by the rules as expected by the user or when
56 developing patterns including negation to match a path previously
57 added with `git add -f`.
58
59 OUTPUT
60 ------
61
62 By default, any of the given pathnames which match an ignore pattern
63 will be output, one per line. If no pattern matches a given path,
64 nothing will be output for that path; this means that path will not be
65 ignored.
66
67 If `--verbose` is specified, the output is a series of lines of the form:
68
69 <source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>
70
71 <pathname> is the path of a file being queried, <pattern> is the
72 matching pattern, <source> is the pattern's source file, and <linenum>
73 is the line number of the pattern within that source. If the pattern
74 contained a `!` prefix or `/` suffix, it will be preserved in the
75 output. <source> will be an absolute path when referring to the file
76 configured by `core.excludesFile`, or relative to the repository root
77 when referring to `.git/info/exclude` or a per-directory exclude file.
78
79 If `-z` is specified, the pathnames in the output are delimited by the
80 null character; if `--verbose` is also specified then null characters
81 are also used instead of colons and hard tabs:
82
83 <source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>
84
85 If `-n` or `--non-matching` are specified, non-matching pathnames will
86 also be output, in which case all fields in each output record except
87 for <pathname> will be empty. This can be useful when running
88 non-interactively, so that files can be incrementally streamed to
89 STDIN of a long-running check-ignore process, and for each of these
90 files, STDOUT will indicate whether that file matched a pattern or
91 not. (Without this option, it would be impossible to tell whether the
92 absence of output for a given file meant that it didn't match any
93 pattern, or that the output hadn't been generated yet.)
94
95 Buffering happens as documented under the `GIT_FLUSH` option in
96 linkgit:git[1]. The caller is responsible for avoiding deadlocks
97 caused by overfilling an input buffer or reading from an empty output
98 buffer.
99
100 EXIT STATUS
101 -----------
102
103 0::
104 One or more of the provided paths is ignored.
105
106 1::
107 None of the provided paths are ignored.
108
109 128::
110 A fatal error was encountered.
111
112 SEE ALSO
113 --------
114 linkgit:gitignore[5]
115 linkgit:git-config[1]
116 linkgit:git-ls-files[1]
117
118 GIT
119 ---
120 Part of the linkgit:git[1] suite