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