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         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