Documentation/git-ls-files.txt

   1 git-ls-files(1)
   2 ===============
   3
   4 NAME
   5 ----
   6 git-ls-files - Show information about files in the index and the working tree
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git ls-files' [-z] [-t] [-v] [-f]
  13                 [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
  14                 [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
  15                 [--resolve-undo]
  16                 [--directory [--no-empty-directory]] [--eol]
  17                 [--deduplicate]
  18                 [-x <pattern>|--exclude=<pattern>]
  19                 [-X <file>|--exclude-from=<file>]
  20                 [--exclude-per-directory=<file>]
  21                 [--exclude-standard]
  22                 [--error-unmatch] [--with-tree=<tree-ish>]
  23                 [--full-name] [--recurse-submodules]
  24                 [--abbrev[=<n>]] [--format=<format>] [--] [<file>...]
  25
  26 DESCRIPTION
  27 -----------
  28 This merges the file listing in the index with the actual working
  29 directory list, and shows different combinations of the two.
  30
  31 One or more of the options below may be used to determine the files
  32 shown:
  33
  34 OPTIONS
  35 -------
  36 -c::
  37 --cached::
  38         Show cached files in the output (default)
  39
  40 -d::
  41 --deleted::
  42         Show deleted files in the output
  43
  44 -m::
  45 --modified::
  46         Show modified files in the output
  47
  48 -o::
  49 --others::
  50         Show other (i.e. untracked) files in the output
  51
  52 -i::
  53 --ignored::
  54         Show only ignored files in the output. When showing files in the
  55         index, print only those matched by an exclude pattern. When
  56         showing "other" files, show only those matched by an exclude
  57         pattern. Standard ignore rules are not automatically activated,
  58         therefore at least one of the `--exclude*` options is required.
  59
  60 -s::
  61 --stage::
  62         Show staged contents' mode bits, object name and stage number in the output.
  63
  64 --directory::
  65         If a whole directory is classified as "other", show just its
  66         name (with a trailing slash) and not its whole contents.
  67
  68 --no-empty-directory::
  69         Do not list empty directories. Has no effect without --directory.
  70
  71 -u::
  72 --unmerged::
  73         Show unmerged files in the output (forces --stage)
  74
  75 -k::
  76 --killed::
  77         Show files on the filesystem that need to be removed due
  78         to file/directory conflicts for checkout-index to
  79         succeed.
  80
  81 --resolve-undo::
  82         Show files having resolve-undo information in the index
  83         together with their resolve-undo information.  (resolve-undo
  84         information is what is used to implement "git checkout -m
  85         $PATH", i.e. to recreate merge conflicts that were
  86         accidentally resolved)
  87
  88 -z::
  89         \0 line termination on output and do not quote filenames.
  90         See OUTPUT below for more information.
  91
  92 --deduplicate::
  93         When only filenames are shown, suppress duplicates that may
  94         come from having multiple stages during a merge, or giving
  95         `--deleted` and `--modified` option at the same time.
  96         When any of the `-t`, `--unmerged`, or `--stage` option is
  97         in use, this option has no effect.
  98
  99 -x <pattern>::
 100 --exclude=<pattern>::
 101         Skip untracked files matching pattern.
 102         Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS
 103         below for more information.
 104
 105 -X <file>::
 106 --exclude-from=<file>::
 107         Read exclude patterns from <file>; 1 per line.
 108
 109 --exclude-per-directory=<file>::
 110         Read additional exclude patterns that apply only to the
 111         directory and its subdirectories in <file>.
 112
 113 --exclude-standard::
 114         Add the standard Git exclusions: .git/info/exclude, .gitignore
 115         in each directory, and the user's global exclusion file.
 116
 117 --error-unmatch::
 118         If any <file> does not appear in the index, treat this as an
 119         error (return 1).
 120
 121 --with-tree=<tree-ish>::
 122         When using --error-unmatch to expand the user supplied
 123         <file> (i.e. path pattern) arguments to paths, pretend
 124         that paths which were removed in the index since the
 125         named <tree-ish> are still present.  Using this option
 126         with `-s` or `-u` options does not make any sense.
 127
 128 -t::
 129         This feature is semi-deprecated. For scripting purpose,
 130         linkgit:git-status[1] `--porcelain` and
 131         linkgit:git-diff-files[1] `--name-status` are almost always
 132         superior alternatives, and users should look at
 133         linkgit:git-status[1] `--short` or linkgit:git-diff[1]
 134         `--name-status` for more user-friendly alternatives.
 135 +
 136 --
 137 This option identifies the file status with the following tags (followed by
 138 a space) at the start of each line:
 139
 140         H::     cached
 141         S::     skip-worktree
 142         M::     unmerged
 143         R::     removed/deleted
 144         C::     modified/changed
 145         K::     to be killed
 146         ?::     other
 147         U::     resolve-undo
 148 --
 149
 150 -v::
 151         Similar to `-t`, but use lowercase letters for files
 152         that are marked as 'assume unchanged' (see
 153         linkgit:git-update-index[1]).
 154
 155 -f::
 156         Similar to `-t`, but use lowercase letters for files
 157         that are marked as 'fsmonitor valid' (see
 158         linkgit:git-update-index[1]).
 159
 160 --full-name::
 161         When run from a subdirectory, the command usually
 162         outputs paths relative to the current directory.  This
 163         option forces paths to be output relative to the project
 164         top directory.
 165
 166 --recurse-submodules::
 167         Recursively calls ls-files on each active submodule in the repository.
 168         Currently there is only support for the --cached and --stage modes.
 169
 170 --abbrev[=<n>]::
 171         Instead of showing the full 40-byte hexadecimal object
 172         lines, show the shortest prefix that is at least '<n>'
 173         hexdigits long that uniquely refers the object.
 174         Non default number of digits can be specified with --abbrev=<n>.
 175
 176 --debug::
 177         After each line that describes a file, add more data about its
 178         cache entry.  This is intended to show as much information as
 179         possible for manual inspection; the exact format may change at
 180         any time.
 181
 182 --eol::
 183         Show <eolinfo> and <eolattr> of files.
 184         <eolinfo> is the file content identification used by Git when
 185         the "text" attribute is "auto" (or not set and core.autocrlf is not false).
 186         <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "".
 187 +
 188 "" means the file is not a regular file, it is not in the index or
 189 not accessible in the working tree.
 190 +
 191 <eolattr> is the attribute that is used when checking out or committing,
 192 it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
 193 Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
 194 +
 195 Both the <eolinfo> in the index ("i/<eolinfo>")
 196 and in the working tree ("w/<eolinfo>") are shown for regular files,
 197 followed by the  ("attr/<eolattr>").
 198
 199 --sparse::
 200         If the index is sparse, show the sparse directories without expanding
 201         to the contained files. Sparse directories will be shown with a
 202         trailing slash, such as "x/" for a sparse directory "x".
 203
 204 --format=<format>::
 205         A string that interpolates `%(fieldname)` from the result being shown.
 206         It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits
 207         interpolates to character with hex code `xx`; for example `%00`
 208         interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF).
 209         --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo`
 210         and `--eol`.
 211 \--::
 212         Do not interpret any more arguments as options.
 213
 214 <file>::
 215         Files to show. If no files are given all files which match the other
 216         specified criteria are shown.
 217
 218 OUTPUT
 219 ------
 220 'git ls-files' just outputs the filenames unless `--stage` is specified in
 221 which case it outputs:
 222
 223         [<tag> ]<mode> <object> <stage> <file>
 224
 225 'git ls-files --eol' will show
 226         i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
 227
 228 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
 229 detailed information on unmerged paths.
 230
 231 For an unmerged path, instead of recording a single mode/SHA-1 pair,
 232 the index records up to three such pairs; one from tree O in stage
 233 1, A in stage 2, and B in stage 3.  This information can be used by
 234 the user (or the porcelain) to see what should eventually be recorded at the
 235 path. (see linkgit:git-read-tree[1] for more information on state)
 236
 237 Without the `-z` option, pathnames with "unusual" characters are
 238 quoted as explained for the configuration variable `core.quotePath`
 239 (see linkgit:git-config[1]).  Using `-z` the filename is output
 240 verbatim and the line is terminated by a NUL byte.
 241
 242 It is possible to print in a custom format by using the `--format`
 243 option, which is able to interpolate different fields using
 244 a `%(fieldname)` notation. For example, if you only care about the
 245 "objectname" and "path" fields, you can execute with a specific
 246 "--format" like
 247
 248         git ls-files --format='%(objectname) %(path)'
 249
 250 FIELD NAMES
 251 -----------
 252 The way each path is shown can be customized by using the
 253 `--format=<format>` option, where the %(fieldname) in the
 254 <format> string for various aspects of the index entry are
 255 interpolated.  The following "fieldname" are understood:
 256
 257 objectmode::
 258         The mode of the file which is recorded in the index.
 259 objectname::
 260         The name of the file which is recorded in the index.
 261 stage::
 262         The stage of the file which is recorded in the index.
 263 eolinfo:index::
 264 eolinfo:worktree::
 265         The <eolinfo> (see the description of the `--eol` option) of
 266         the contents in the index or in the worktree for the path.
 267 eolattr::
 268         The <eolattr> (see the description of the `--eol` option)
 269         that applies to the path.
 270 path::
 271         The pathname of the file which is recorded in the index.
 272
 273 EXCLUDE PATTERNS
 274 ----------------
 275
 276 'git ls-files' can use a list of "exclude patterns" when
 277 traversing the directory tree and finding files to show when the
 278 flags --others or --ignored are specified.  linkgit:gitignore[5]
 279 specifies the format of exclude patterns.
 280
 281 These exclude patterns come from these places, in order:
 282
 283   1. The command-line flag --exclude=<pattern> specifies a
 284      single pattern.  Patterns are ordered in the same order
 285      they appear in the command line.
 286
 287   2. The command-line flag --exclude-from=<file> specifies a
 288      file containing a list of patterns.  Patterns are ordered
 289      in the same order they appear in the file.
 290
 291   3. The command-line flag --exclude-per-directory=<name> specifies
 292      a name of the file in each directory 'git ls-files'
 293      examines, normally `.gitignore`.  Files in deeper
 294      directories take precedence.  Patterns are ordered in the
 295      same order they appear in the files.
 296
 297 A pattern specified on the command line with --exclude or read
 298 from the file specified with --exclude-from is relative to the
 299 top of the directory tree.  A pattern read from a file specified
 300 by --exclude-per-directory is relative to the directory that the
 301 pattern file appears in.
 302
 303 SEE ALSO
 304 --------
 305 linkgit:git-read-tree[1], linkgit:gitignore[5]
 306
 307 GIT
 308 ---
 309 Part of the linkgit:git[1] suite