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