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