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                 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
  14                 (-[c|d|o|i|s|u|k|m])*
  15                 [--eol]
  16                 [-x <pattern>|--exclude=<pattern>]
  17                 [-X <file>|--exclude-from=<file>]
  18                 [--exclude-per-directory=<file>]
  19                 [--exclude-standard]
  20                 [--error-unmatch] [--with-tree=<tree-ish>]
  21                 [--full-name] [--recurse-submodules]
  22                 [--abbrev] [--] [<file>...]
  23
  24 DESCRIPTION
  25 -----------
  26 This merges the file listing in the directory cache index with the
  27 actual working directory list, and shows different combinations of the
  28 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 -x <pattern>::
  85 --exclude=<pattern>::
  86         Skip untracked files matching pattern.
  87         Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS
  88         below for more information.
  89
  90 -X <file>::
  91 --exclude-from=<file>::
  92         Read exclude patterns from <file>; 1 per line.
  93
  94 --exclude-per-directory=<file>::
  95         Read additional exclude patterns that apply only to the
  96         directory and its subdirectories in <file>.
  97
  98 --exclude-standard::
  99         Add the standard Git exclusions: .git/info/exclude, .gitignore
 100         in each directory, and the user's global exclusion file.
 101
 102 --error-unmatch::
 103         If any <file> does not appear in the index, treat this as an
 104         error (return 1).
 105
 106 --with-tree=<tree-ish>::
 107         When using --error-unmatch to expand the user supplied
 108         <file> (i.e. path pattern) arguments to paths, pretend
 109         that paths which were removed in the index since the
 110         named <tree-ish> are still present.  Using this option
 111         with `-s` or `-u` options does not make any sense.
 112
 113 -t::
 114         This feature is semi-deprecated. For scripting purpose,
 115         linkgit:git-status[1] `--porcelain` and
 116         linkgit:git-diff-files[1] `--name-status` are almost always
 117         superior alternatives, and users should look at
 118         linkgit:git-status[1] `--short` or linkgit:git-diff[1]
 119         `--name-status` for more user-friendly alternatives.
 120 +
 121 This option identifies the file status with the following tags (followed by
 122 a space) at the start of each line:
 123
 124         H::     cached
 125         S::     skip-worktree
 126         M::     unmerged
 127         R::     removed/deleted
 128         C::     modified/changed
 129         K::     to be killed
 130         ?::     other
 131
 132 -v::
 133         Similar to `-t`, but use lowercase letters for files
 134         that are marked as 'assume unchanged' (see
 135         linkgit:git-update-index[1]).
 136
 137 -f::
 138         Similar to `-t`, but use lowercase letters for files
 139         that are marked as 'fsmonitor valid' (see
 140         linkgit:git-update-index[1]).
 141
 142 --full-name::
 143         When run from a subdirectory, the command usually
 144         outputs paths relative to the current directory.  This
 145         option forces paths to be output relative to the project
 146         top directory.
 147
 148 --recurse-submodules::
 149         Recursively calls ls-files on each submodule in the repository.
 150         Currently there is only support for the --cached mode.
 151
 152 --abbrev[=<n>]::
 153         Instead of showing the full 40-byte hexadecimal object
 154         lines, show only a partial prefix.
 155         Non default number of digits can be specified with --abbrev=<n>.
 156
 157 --debug::
 158         After each line that describes a file, add more data about its
 159         cache entry.  This is intended to show as much information as
 160         possible for manual inspection; the exact format may change at
 161         any time.
 162
 163 --eol::
 164         Show <eolinfo> and <eolattr> of files.
 165         <eolinfo> is the file content identification used by Git when
 166         the "text" attribute is "auto" (or not set and core.autocrlf is not false).
 167         <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "".
 168 +
 169 "" means the file is not a regular file, it is not in the index or
 170 not accessible in the working tree.
 171 +
 172 <eolattr> is the attribute that is used when checking out or committing,
 173 it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
 174 Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
 175 +
 176 Both the <eolinfo> in the index ("i/<eolinfo>")
 177 and in the working tree ("w/<eolinfo>") are shown for regular files,
 178 followed by the  ("attr/<eolattr>").
 179
 180 \--::
 181         Do not interpret any more arguments as options.
 182
 183 <file>::
 184         Files to show. If no files are given all files which match the other
 185         specified criteria are shown.
 186
 187 OUTPUT
 188 ------
 189 'git ls-files' just outputs the filenames unless `--stage` is specified in
 190 which case it outputs:
 191
 192         [<tag> ]<mode> <object> <stage> <file>
 193
 194 'git ls-files --eol' will show
 195         i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
 196
 197 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
 198 detailed information on unmerged paths.
 199
 200 For an unmerged path, instead of recording a single mode/SHA-1 pair,
 201 the index records up to three such pairs; one from tree O in stage
 202 1, A in stage 2, and B in stage 3.  This information can be used by
 203 the user (or the porcelain) to see what should eventually be recorded at the
 204 path. (see linkgit:git-read-tree[1] for more information on state)
 205
 206 Without the `-z` option, pathnames with "unusual" characters are
 207 quoted as explained for the configuration variable `core.quotePath`
 208 (see linkgit:git-config[1]).  Using `-z` the filename is output
 209 verbatim and the line is terminated by a NUL byte.
 210
 211
 212 EXCLUDE PATTERNS
 213 ----------------
 214
 215 'git ls-files' can use a list of "exclude patterns" when
 216 traversing the directory tree and finding files to show when the
 217 flags --others or --ignored are specified.  linkgit:gitignore[5]
 218 specifies the format of exclude patterns.
 219
 220 These exclude patterns come from these places, in order:
 221
 222   1. The command-line flag --exclude=<pattern> specifies a
 223      single pattern.  Patterns are ordered in the same order
 224      they appear in the command line.
 225
 226   2. The command-line flag --exclude-from=<file> specifies a
 227      file containing a list of patterns.  Patterns are ordered
 228      in the same order they appear in the file.
 229
 230   3. The command-line flag --exclude-per-directory=<name> specifies
 231      a name of the file in each directory 'git ls-files'
 232      examines, normally `.gitignore`.  Files in deeper
 233      directories take precedence.  Patterns are ordered in the
 234      same order they appear in the files.
 235
 236 A pattern specified on the command line with --exclude or read
 237 from the file specified with --exclude-from is relative to the
 238 top of the directory tree.  A pattern read from a file specified
 239 by --exclude-per-directory is relative to the directory that the
 240 pattern file appears in.
 241
 242 SEE ALSO
 243 --------
 244 linkgit:git-read-tree[1], linkgit:gitignore[5]
 245
 246 GIT
 247 ---
 248 Part of the linkgit:git[1] suite