man1/git-ls-files.1

   1 .\"Generated by db2man.xsl. Don't modify this, modify the source.
   2 .de Sh \" Subsection
   3 .br
   4 .if t .Sp
   5 .ne 5
   6 .PP
   7 \fB\\$1\fR
   8 .PP
   9 ..
  10 .de Sp \" Vertical space (when we can't use .PP)
  11 .if t .sp .5v
  12 .if n .sp
  13 ..
  14 .de Ip \" List item
  15 .br
  16 .ie \\n(.$>=3 .ne \\$3
  17 .el .ne 3
  18 .IP "\\$1" \\$2
  19 ..
  20 .TH "GIT-LS-FILES" 1 "" "" ""
  21 .SH NAME
  22 git-ls-files \- Information about files in the index/working directory
  23 .SH "SYNOPSIS"
  24
  25 .nf
  26 \fIgit\-ls\-files\fR [\-z] [\-t] [\-v]
  27                 (\-\-[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
  28                 (\-[c|d|o|i|s|u|k|m])*
  29                 [\-x <pattern>|\-\-exclude=<pattern>]
  30                 [\-X <file>|\-\-exclude\-from=<file>]
  31                 [\-\-exclude\-per\-directory=<file>]
  32                 [\-\-error\-unmatch]
  33                 [\-\-full\-name] [\-\-] [<file>]*
  34 .fi
  35
  36 .SH "DESCRIPTION"
  37
  38
  39 This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two\&.
  40
  41
  42 One or more of the options below may be used to determine the files shown:
  43
  44 .SH "OPTIONS"
  45
  46 .TP
  47 \-c|\-\-cached
  48 Show cached files in the output (default)
  49
  50 .TP
  51 \-d|\-\-deleted
  52 Show deleted files in the output
  53
  54 .TP
  55 \-m|\-\-modified
  56 Show modified files in the output
  57
  58 .TP
  59 \-o|\-\-others
  60 Show other files in the output
  61
  62 .TP
  63 \-i|\-\-ignored
  64 Show ignored files in the output Note the this also reverses any exclude list present\&.
  65
  66 .TP
  67 \-s|\-\-stage
  68 Show stage files in the output
  69
  70 .TP
  71 \-\-directory
  72 If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents\&.
  73
  74 .TP
  75 \-\-no\-empty\-directory
  76 Do not list empty directories\&. Has no effect without \-\-directory\&.
  77
  78 .TP
  79 \-u|\-\-unmerged
  80 Show unmerged files in the output (forces \-\-stage)
  81
  82 .TP
  83 \-k|\-\-killed
  84 Show files on the filesystem that need to be removed due to file/directory conflicts for checkout\-index to succeed\&.
  85
  86 .TP
  87 \-z
  88 \\0 line termination on output\&.
  89
  90 .TP
  91 \-x|\-\-exclude=<pattern>
  92 Skips files matching pattern\&. Note that pattern is a shell wildcard pattern\&.
  93
  94 .TP
  95 \-X|\-\-exclude\-from=<file>
  96 exclude patterns are read from <file>; 1 per line\&.
  97
  98 .TP
  99 \-\-exclude\-per\-directory=<file>
 100 read additional exclude patterns that apply only to the directory and its subdirectories in <file>\&.
 101
 102 .TP
 103 \-\-error\-unmatch
 104 If any <file> does not appear in the index, treat this as an error (return 1)\&.
 105
 106 .TP
 107 \-t
 108 Identify the file status with the following tags (followed by a space) at the start of each line:
 109 H
 110
 111 cached
 112
 113 M
 114
 115 unmerged
 116
 117 R
 118
 119 removed/deleted
 120
 121 C
 122
 123 modified/changed
 124
 125 K
 126
 127 to be killed
 128
 129 ?
 130
 131 other
 132
 133
 134 .TP
 135 \-v
 136 Similar to \-t, but use lowercase letters for files that are marked as \fIalways matching index\fR\&.
 137
 138 .TP
 139 \-\-full\-name
 140 When run from a subdirectory, the command usually outputs paths relative to the current directory\&. This option forces paths to be output relative to the project top directory\&.
 141
 142 .TP
 143 --
 144 Do not interpret any more arguments as options\&.
 145
 146 .TP
 147 <file>
 148 Files to show\&. If no files are given all files which match the other specified criteria are shown\&.
 149
 150 .SH "OUTPUT"
 151
 152
 153 show files just outputs the filename unless \fI\-\-stage\fR is specified in which case it outputs:
 154
 155 .nf
 156 [<tag> ]<mode> <object> <stage> <file>
 157 .fi
 158
 159
 160 "git\-ls\-files \-\-unmerged" and "git\-ls\-files \-\-stage" can be used to examine detailed information on unmerged paths\&.
 161
 162
 163 For an unmerged path, instead of recording a single mode/SHA1 pair, the dircache records up to three such pairs; one from tree O in stage 1, A in stage 2, and B in stage 3\&. This information can be used by the user (or the porcelain) to see what should eventually be recorded at the path\&. (see git\-read\-tree for more information on state)
 164
 165
 166 When \-z option is not used, TAB, LF, and backslash characters in pathnames are represented as \\t, \\n, and \\\\, respectively\&.
 167
 168 .SH "EXCLUDE PATTERNS"
 169
 170
 171 \fIgit\-ls\-files\fR can use a list of "exclude patterns" when traversing the directory tree and finding files to show when the flags \-\-others or \-\-ignored are specified\&.
 172
 173
 174 These exclude patterns come from these places:
 175
 176 .TP 3
 177 1.
 178 command line flag \-\-exclude=<pattern> specifies a single pattern\&.
 179 .TP
 180 2.
 181 command line flag \-\-exclude\-from=<file> specifies a list of patterns stored in a file\&.
 182 .TP
 183 3.
 184 command line flag \-\-exclude\-per\-directory=<name> specifies a name of the file in each directory \fIgit\-ls\-files\fR examines, and if exists, its contents are used as an additional list of patterns\&.
 185 .LP
 186
 187
 188 An exclude pattern file used by (2) and (3) contains one pattern per line\&. A line that starts with a \fI#\fR can be used as comment for readability\&.
 189
 190
 191 There are three lists of patterns that are in effect at a given time\&. They are built and ordered in the following way:
 192
 193 .TP 3
 194 \(bu
 195 \-\-exclude=<pattern> from the command line; patterns are ordered in the same order as they appear on the command line\&.
 196 .TP
 197 \(bu
 198 lines read from \-\-exclude\-from=<file>; patterns are ordered in the same order as they appear in the file\&.
 199 .TP
 200 \(bu
 201 When \-\-exclude\-per\-directory=<name> is specified, upon entering a directory that has such a file, its contents are appended at the end of the current "list of patterns"\&. They are popped off when leaving the directory\&.
 202 .LP
 203
 204
 205 Each pattern in the pattern list specifies "a match pattern" and optionally the fate; either a file that matches the pattern is considered excluded or included\&. A filename is matched against the patterns in the three lists; the \-\-exclude\-from list is checked first, then the \-\-exclude\-per\-directory list, and then finally the \-\-exclude list\&. The last match determines its fate\&. If there is no match in the three lists, the fate is "included"\&.
 206
 207
 208 A pattern specified on the command line with \-\-exclude or read from the file specified with \-\-exclude\-from is relative to the top of the directory tree\&. A pattern read from a file specified by \-\-exclude\-per\-directory is relative to the directory that the pattern file appears in\&.
 209
 210
 211 An exclude pattern is of the following format:
 212
 213 .TP 3
 214 \(bu
 215 an optional prefix \fI!\fR which means that the fate this pattern specifies is "include", not the usual "exclude"; the remainder of the pattern string is interpreted according to the following rules\&.
 216 .TP
 217 \(bu
 218 if it does not contain a slash \fI/\fR, it is a shell glob pattern and used to match against the filename without leading directories (i\&.e\&. the same way as the current implementation)\&.
 219 .TP
 220 \(bu
 221 otherwise, it is a shell glob pattern, suitable for consumption by fnmatch(3) with FNM_PATHNAME flag\&. I\&.e\&. a slash in the pattern must match a slash in the pathname\&. "Documentation/*\&.html" matches "Documentation/git\&.html" but not "ppc/ppc\&.html"\&. As a natural exception, "/*\&.c" matches "cat\-file\&.c" but not "mozilla\-sha1/sha1\&.c"\&.
 222 .LP
 223
 224
 225 An example:
 226
 227 .nf
 228     $ cat \&.git/ignore
 229     # ignore objects and archives, anywhere in the tree\&.
 230     *\&.[oa]
 231     $ cat Documentation/\&.gitignore
 232     # ignore generated html files,
 233     *\&.html
 234     # except foo\&.html which is maintained by hand
 235     !foo\&.html
 236     $ git\-ls\-files \-\-ignored \\
 237         \-\-exclude='Documentation/*\&.[0\-9]' \\
 238         \-\-exclude\-from=\&.git/ignore \\
 239         \-\-exclude\-per\-directory=\&.gitignore
 240 .fi
 241
 242 .SH "SEE ALSO"
 243
 244
 245 \fBgit\-read\-tree\fR(1)
 246
 247 .SH "AUTHOR"
 248
 249
 250 Written by Linus Torvalds <torvalds@osdl\&.org>
 251
 252 .SH "DOCUMENTATION"
 253
 254
 255 Documentation by David Greaves, Junio C Hamano and the git\-list <git@vger\&.kernel\&.org>\&.
 256
 257 .SH "GIT"
 258
 259
 260 Part of the \fBgit\fR(7) suite
 261