Documentation/git-ls-files.txt

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