man1/git-check-ignore.1

   1 '\" t
   2 .\"     Title: git-check-ignore
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-30
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.0.rc0.18.ge9356ba3ea
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CHECK\-IGNORE" "1" "2024-09-30" "Git 2\&.47\&.0\&.rc0\&.18\&.ge" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-check-ignore \- Debug gitignore / exclude files
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit check\-ignore\fR [<options>] <pathname>\&...\:
  36 \fIgit check\-ignore\fR [<options>] \-\-stdin
  37 .fi
  38 .SH "DESCRIPTION"
  39 .sp
  40 For each pathname given via the command\-line or from a file via \fB\-\-stdin\fR, check whether the file is excluded by \&.gitignore (or other input files to the exclude mechanism) and output the path if it is excluded\&.
  41 .sp
  42 By default, tracked files are not shown at all since they are not subject to exclude rules; but see \(lq\-\-no\-index\(rq\&.
  43 .SH "OPTIONS"
  44 .PP
  45 \-q, \-\-quiet
  46 .RS 4
  47 Don\(cqt output anything, just set exit status\&. This is only valid with a single pathname\&.
  48 .RE
  49 .PP
  50 \-v, \-\-verbose
  51 .RS 4
  52 Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path\&. (Matching an exclude pattern usually means the path is excluded, but if the pattern begins with "\fB!\fR" then it is a negated pattern and matching it means the path is NOT excluded\&.)
  53 .sp
  54 For precedence rules within and between exclude sources, see
  55 \fBgitignore\fR(5)\&.
  56 .RE
  57 .PP
  58 \-\-stdin
  59 .RS 4
  60 Read pathnames from the standard input, one per line, instead of from the command\-line\&.
  61 .RE
  62 .PP
  63 \-z
  64 .RS 4
  65 The output format is modified to be machine\-parsable (see below)\&. If
  66 \fB\-\-stdin\fR
  67 is also given, input paths are separated with a NUL character instead of a linefeed character\&.
  68 .RE
  69 .PP
  70 \-n, \-\-non\-matching
  71 .RS 4
  72 Show given paths which don\(cqt match any pattern\&. This only makes sense when
  73 \fB\-\-verbose\fR
  74 is enabled, otherwise it would not be possible to distinguish between paths which match a pattern and those which don\(cqt\&.
  75 .RE
  76 .PP
  77 \-\-no\-index
  78 .RS 4
  79 Don\(cqt look in the index when undertaking the checks\&. This can be used to debug why a path became tracked by e\&.g\&.
  80 \fBgit add \&.\fR
  81 and was not ignored by the rules as expected by the user or when developing patterns including negation to match a path previously added with
  82 \fBgit add \-f\fR\&.
  83 .RE
  84 .SH "OUTPUT"
  85 .sp
  86 By default, any of the given pathnames which match an ignore pattern will be output, one per line\&. If no pattern matches a given path, nothing will be output for that path; this means that path will not be ignored\&.
  87 .sp
  88 If \fB\-\-verbose\fR is specified, the output is a series of lines of the form:
  89 .sp
  90 <source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>
  91 .sp
  92 <pathname> is the path of a file being queried, <pattern> is the matching pattern, <source> is the pattern\(cqs source file, and <linenum> is the line number of the pattern within that source\&. If the pattern contained a "\fB!\fR" prefix or "\fB/\fR" suffix, it will be preserved in the output\&. <source> will be an absolute path when referring to the file configured by \fBcore\&.excludesFile\fR, or relative to the repository root when referring to \fB\&.git/info/exclude\fR or a per\-directory exclude file\&.
  93 .sp
  94 If \fB\-z\fR is specified, the pathnames in the output are delimited by the null character; if \fB\-\-verbose\fR is also specified then null characters are also used instead of colons and hard tabs:
  95 .sp
  96 <source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>
  97 .sp
  98 If \fB\-n\fR or \fB\-\-non\-matching\fR are specified, non\-matching pathnames will also be output, in which case all fields in each output record except for <pathname> will be empty\&. This can be useful when running non\-interactively, so that files can be incrementally streamed to STDIN of a long\-running check\-ignore process, and for each of these files, STDOUT will indicate whether that file matched a pattern or not\&. (Without this option, it would be impossible to tell whether the absence of output for a given file meant that it didn\(cqt match any pattern, or that the output hadn\(cqt been generated yet\&.)
  99 .sp
 100 Buffering happens as documented under the \fBGIT_FLUSH\fR option in \fBgit\fR(1)\&. The caller is responsible for avoiding deadlocks caused by overfilling an input buffer or reading from an empty output buffer\&.
 101 .SH "EXIT STATUS"
 102 .PP
 103 0
 104 .RS 4
 105 One or more of the provided paths is ignored\&.
 106 .RE
 107 .PP
 108 1
 109 .RS 4
 110 None of the provided paths are ignored\&.
 111 .RE
 112 .PP
 113 128
 114 .RS 4
 115 A fatal error was encountered\&.
 116 .RE
 117 .SH "SEE ALSO"
 118 .sp
 119 \fBgitignore\fR(5) \fBgit-config\fR(1) \fBgit-ls-files\fR(1)
 120 .SH "GIT"
 121 .sp
 122 Part of the \fBgit\fR(1) suite