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 git\-ls\-files [\-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 cached
  95 M
  96 unmerged
  97 R
  98 removed/deleted
  99 C
 100 modified/changed
 101 K
 102 to be killed ? other
 103
 104 .TP
 105 \-\-full\-name
 106 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\&.
 107
 108 .TP
 109 --
 110 Do not interpret any more arguments as options\&.
 111
 112 .TP
 113 <file>
 114 Files to show\&. If no files are given all files which match the other specified criteria are shown\&.
 115
 116 .SH "OUTPUT"
 117
 118
 119 show files just outputs the filename unless \-\-stage is specified in which case it outputs:
 120
 121 .nf
 122 [<tag> ]<mode> <object> <stage> <file>
 123 .fi
 124
 125
 126 "git\-ls\-files \-\-unmerged" and "git\-ls\-files \-\-stage" can be used to examine detailed information on unmerged paths\&.
 127
 128
 129 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)
 130
 131
 132 When \-z option is not used, TAB, LF, and backslash characters in pathnames are represented as \\t, \\n, and \\\\, respectively\&.
 133
 134 .SH "EXCLUDE PATTERNS"
 135
 136
 137 git\-ls\-files 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\&.
 138
 139
 140 These exclude patterns come from these places:
 141
 142 .TP 3
 143 1.
 144 command line flag \-\-exclude=<pattern> specifies a single pattern\&.
 145 .TP
 146 2.
 147 command line flag \-\-exclude\-from=<file> specifies a list of patterns stored in a file\&.
 148 .TP
 149 3.
 150 command line flag \-\-exclude\-per\-directory=<name> specifies a name of the file in each directory git\-ls\-files examines, and if exists, its contents are used as an additional list of patterns\&.
 151 .LP
 152
 153
 154 An exclude pattern file used by (2) and (3) contains one pattern per line\&. A line that starts with a # can be used as comment for readability\&.
 155
 156
 157 There are three lists of patterns that are in effect at a given time\&. They are built and ordered in the following way:
 158
 159 .TP 3
 160 \(bu
 161 \-\-exclude=<pattern> from the command line; patterns are ordered in the same order as they appear on the command line\&.
 162 .TP
 163 \(bu
 164 lines read from \-\-exclude\-from=<file>; patterns are ordered in the same order as they appear in the file\&.
 165 .TP
 166 \(bu
 167 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\&.
 168 .LP
 169
 170
 171 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"\&.
 172
 173
 174 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\&.
 175
 176
 177 An exclude pattern is of the following format:
 178
 179 .TP 3
 180 \(bu
 181 an optional prefix ! 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\&.
 182 .TP
 183 \(bu
 184 if it does not contain a slash /, 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)\&.
 185 .TP
 186 \(bu
 187 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"\&.
 188 .LP
 189
 190
 191 An example:
 192
 193 .IP
 194     $ cat \&.git/ignore
 195     # ignore objects and archives, anywhere in the tree\&.
 196     *\&.[oa]
 197     $ cat Documentation/\&.gitignore
 198     # ignore generated html files,
 199     *\&.html
 200     # except foo\&.html which is maintained by hand
 201     !foo\&.html
 202     $ git\-ls\-files \-\-ignored \\
 203         \-\-exclude='Documentation/*\&.[0\-9]' \\
 204         \-\-exclude\-from=\&.git/ignore \\
 205         \-\-exclude\-per\-directory=\&.gitignore
 206 .SH "SEE ALSO"
 207
 208
 209 \fBgit\-read\-tree\fR(1)
 210
 211 .SH "AUTHOR"
 212
 213
 214 Written by Linus Torvalds <torvalds@osdl\&.org>
 215
 216 .SH "DOCUMENTATION"
 217
 218
 219 Documentation by David Greaves, Junio C Hamano and the git\-list <git@vger\&.kernel\&.org>\&.
 220
 221 .SH "GIT"
 222
 223
 224 Part of the \fBgit\fR(7) suite
 225