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 \-u|\-\-unmerged
  76 Show unmerged files in the output (forces \-\-stage)
  77
  78 .TP
  79 \-k|\-\-killed
  80 Show files on the filesystem that need to be removed due to file/directory conflicts for checkout\-index to succeed\&.
  81
  82 .TP
  83 \-z
  84 \\0 line termination on output\&.
  85
  86 .TP
  87 \-x|\-\-exclude=<pattern>
  88 Skips files matching pattern\&. Note that pattern is a shell wildcard pattern\&.
  89
  90 .TP
  91 \-X|\-\-exclude\-from=<file>
  92 exclude patterns are read from <file>; 1 per line\&.
  93
  94 .TP
  95 \-\-exclude\-per\-directory=<file>
  96 read additional exclude patterns that apply only to the directory and its subdirectories in <file>\&.
  97
  98 .TP
  99 \-\-error\-unmatch
 100 If any <file> does not appear in the index, treat this as an error (return 1)\&.
 101
 102 .TP
 103 \-t
 104 Identify the file status with the following tags (followed by a space) at the start of each line:
 105 H
 106
 107 cached
 108
 109 M
 110
 111 unmerged
 112
 113 R
 114
 115 removed/deleted
 116
 117 C
 118
 119 modified/changed
 120
 121 K
 122
 123 to be killed
 124
 125 ?
 126
 127 other
 128
 129
 130 .TP
 131 \-v
 132 Similar to \-t, but use lowercase letters for files that are marked as \fIalways matching index\fR\&.
 133
 134 .TP
 135 \-\-full\-name
 136 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\&.
 137
 138 .TP
 139 --
 140 Do not interpret any more arguments as options\&.
 141
 142 .TP
 143 <file>
 144 Files to show\&. If no files are given all files which match the other specified criteria are shown\&.
 145
 146 .SH "OUTPUT"
 147
 148
 149 show files just outputs the filename unless \fI\-\-stage\fR is specified in which case it outputs:
 150
 151 .nf
 152 [<tag> ]<mode> <object> <stage> <file>
 153 .fi
 154
 155
 156 "git\-ls\-files \-\-unmerged" and "git\-ls\-files \-\-stage" can be used to examine detailed information on unmerged paths\&.
 157
 158
 159 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)
 160
 161
 162 When \-z option is not used, TAB, LF, and backslash characters in pathnames are represented as \\t, \\n, and \\\\, respectively\&.
 163
 164 .SH "EXCLUDE PATTERNS"
 165
 166
 167 \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\&.
 168
 169
 170 These exclude patterns come from these places:
 171
 172 .TP 3
 173 1.
 174 command line flag \-\-exclude=<pattern> specifies a single pattern\&.
 175 .TP
 176 2.
 177 command line flag \-\-exclude\-from=<file> specifies a list of patterns stored in a file\&.
 178 .TP
 179 3.
 180 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\&.
 181 .LP
 182
 183
 184 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\&.
 185
 186
 187 There are three lists of patterns that are in effect at a given time\&. They are built and ordered in the following way:
 188
 189 .TP 3
 190 \(bu
 191 \-\-exclude=<pattern> from the command line; patterns are ordered in the same order as they appear on the command line\&.
 192 .TP
 193 \(bu
 194 lines read from \-\-exclude\-from=<file>; patterns are ordered in the same order as they appear in the file\&.
 195 .TP
 196 \(bu
 197 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\&.
 198 .LP
 199
 200
 201 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"\&.
 202
 203
 204 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\&.
 205
 206
 207 An exclude pattern is of the following format:
 208
 209 .TP 3
 210 \(bu
 211 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\&.
 212 .TP
 213 \(bu
 214 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)\&.
 215 .TP
 216 \(bu
 217 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"\&.
 218 .LP
 219
 220
 221 An example:
 222
 223 .IP
 224     $ cat \&.git/ignore
 225     # ignore objects and archives, anywhere in the tree\&.
 226     *\&.[oa]
 227     $ cat Documentation/\&.gitignore
 228     # ignore generated html files,
 229     *\&.html
 230     # except foo\&.html which is maintained by hand
 231     !foo\&.html
 232     $ git\-ls\-files \-\-ignored \\
 233         \-\-exclude='Documentation/*\&.[0\-9]' \\
 234         \-\-exclude\-from=\&.git/ignore \\
 235         \-\-exclude\-per\-directory=\&.gitignore
 236 .SH "SEE ALSO"
 237
 238
 239 \fBgit\-read\-tree\fR(1)
 240
 241 .SH "AUTHOR"
 242
 243
 244 Written by Linus Torvalds <torvalds@osdl\&.org>
 245
 246 .SH "DOCUMENTATION"
 247
 248
 249 Documentation by David Greaves, Junio C Hamano and the git\-list <git@vger\&.kernel\&.org>\&.
 250
 251 .SH "GIT"
 252
 253
 254 Part of the \fBgit\fR(7) suite
 255