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
  26 \fIgit\-ls\-files\fR [\-z] [\-t] (\-\-[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (\-[c|d|o|i|s|u|k|m])* [\-x <pattern>|\-\-exclude=<pattern>] [\-X <file>|\-\-exclude\-from=<file>] [\-\-exclude\-per\-directory=<file>] [\-\-full\-name] [\-\-] [<file>]*
  27
  28 .SH "DESCRIPTION"
  29
  30
  31 This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two\&.
  32
  33
  34 One or more of the options below may be used to determine the files shown:
  35
  36 .SH "OPTIONS"
  37
  38 .TP
  39 \-c|\-\-cached
  40 Show cached files in the output (default)
  41
  42 .TP
  43 \-d|\-\-deleted
  44 Show deleted files in the output
  45
  46 .TP
  47 \-m|\-\-modified
  48 Show modified files in the output
  49
  50 .TP
  51 \-o|\-\-others
  52 Show other files in the output
  53
  54 .TP
  55 \-i|\-\-ignored
  56 Show ignored files in the output Note the this also reverses any exclude list present\&.
  57
  58 .TP
  59 \-s|\-\-stage
  60 Show stage files in the output
  61
  62 .TP
  63 \-\-directory
  64 If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents\&.
  65
  66 .TP
  67 \-u|\-\-unmerged
  68 Show unmerged files in the output (forces \-\-stage)
  69
  70 .TP
  71 \-k|\-\-killed
  72 Show files on the filesystem that need to be removed due to file/directory conflicts for checkout\-index to succeed\&.
  73
  74 .TP
  75 \-z
  76 \\0 line termination on output\&.
  77
  78 .TP
  79 \-x|\-\-exclude=<pattern>
  80 Skips files matching pattern\&. Note that pattern is a shell wildcard pattern\&.
  81
  82 .TP
  83 \-X|\-\-exclude\-from=<file>
  84 exclude patterns are read from <file>; 1 per line\&.
  85
  86 .TP
  87 \-\-exclude\-per\-directory=<file>
  88 read additional exclude patterns that apply only to the directory and its subdirectories in <file>\&.
  89
  90 .TP
  91 \-t
  92 Identify the file status with the following tags (followed by a space) at the start of each line:
  93 H
  94
  95 cached
  96
  97 M
  98
  99 unmerged
 100
 101 R
 102
 103 removed/deleted
 104
 105 C
 106
 107 modified/changed
 108
 109 K
 110
 111 to be killed
 112
 113 ?
 114
 115 other
 116
 117
 118 .TP
 119 \-\-full\-name
 120 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\&.
 121
 122 .TP
 123 --
 124 Do not interpret any more arguments as options\&.
 125
 126 .TP
 127 <file>
 128 Files to show\&. If no files are given all files which match the other specified criteria are shown\&.
 129
 130 .SH "OUTPUT"
 131
 132
 133 show files just outputs the filename unless \fI\-\-stage\fR is specified in which case it outputs:
 134
 135 .nf
 136 [<tag> ]<mode> <object> <stage> <file>
 137 .fi
 138
 139
 140 "git\-ls\-files \-\-unmerged" and "git\-ls\-files \-\-stage" can be used to examine detailed information on unmerged paths\&.
 141
 142
 143 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)
 144
 145
 146 When \-z option is not used, TAB, LF, and backslash characters in pathnames are represented as \\t, \\n, and \\\\, respectively\&.
 147
 148 .SH "EXCLUDE PATTERNS"
 149
 150
 151 \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\&.
 152
 153
 154 These exclude patterns come from these places:
 155
 156 .TP 3
 157 1.
 158 command line flag \-\-exclude=<pattern> specifies a single pattern\&.
 159 .TP
 160 2.
 161 command line flag \-\-exclude\-from=<file> specifies a list of patterns stored in a file\&.
 162 .TP
 163 3.
 164 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\&.
 165 .LP
 166
 167
 168 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\&.
 169
 170
 171 There are three lists of patterns that are in effect at a given time\&. They are built and ordered in the following way:
 172
 173 .TP 3
 174 \(bu
 175 \-\-exclude=<pattern> from the command line; patterns are ordered in the same order as they appear on the command line\&.
 176 .TP
 177 \(bu
 178 lines read from \-\-exclude\-from=<file>; patterns are ordered in the same order as they appear in the file\&.
 179 .TP
 180 \(bu
 181 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\&.
 182 .LP
 183
 184
 185 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"\&.
 186
 187
 188 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\&.
 189
 190
 191 An exclude pattern is of the following format:
 192
 193 .TP 3
 194 \(bu
 195 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\&.
 196 .TP
 197 \(bu
 198 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)\&.
 199 .TP
 200 \(bu
 201 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"\&.
 202 .LP
 203
 204
 205 An example:
 206
 207 .IP
 208     $ cat \&.git/ignore
 209     # ignore objects and archives, anywhere in the tree\&.
 210     *\&.[oa]
 211     $ cat Documentation/\&.gitignore
 212     # ignore generated html files,
 213     *\&.html
 214     # except foo\&.html which is maintained by hand
 215     !foo\&.html
 216     $ git\-ls\-files \-\-ignored \\
 217         \-\-exclude='Documentation/*\&.[0\-9]' \\
 218         \-\-exclude\-from=\&.git/ignore \\
 219         \-\-exclude\-per\-directory=\&.gitignore
 220 .SH "SEE ALSO"
 221
 222
 223 \fBgit\-read\-tree\fR(1)
 224
 225 .SH "AUTHOR"
 226
 227
 228 Written by Linus Torvalds <torvalds@osdl\&.org>
 229
 230 .SH "DOCUMENTATION"
 231
 232
 233 Documentation by David Greaves, Junio C Hamano and the git\-list <git@vger\&.kernel\&.org>\&.
 234
 235 .SH "GIT"
 236
 237
 238 Part of the \fBgit\fR(7) suite
 239