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