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`, show the pattern from .gitignore (or other input files to
  20 the exclude mechanism) that decides if the pathname is excluded or
  21 included.  Later patterns within a file take precedence over earlier
  22 ones.
  23
  24 By default, tracked files are not shown at all since they are not
  25 subject to exclude rules; but see `--no-index'.
  26
  27 OPTIONS
  28 -------
  29 -q, --quiet::
  30         Don't output anything, just set exit status.  This is only
  31         valid with a single pathname.
  32
  33 -v, --verbose::
  34         Also output details about the matching pattern (if any)
  35         for each given pathname.
  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:gitconfig[5]
 116 linkgit:git-ls-files[1]
 117
 118 GIT
 119 ---
 120 Part of the linkgit:git[1] suite