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[=<n>]] [--] [<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 --
 122 This option identifies the file status with the following tags (followed by
 123 a space) at the start of each line:
 124
 125         H::     cached
 126         S::     skip-worktree
 127         M::     unmerged
 128         R::     removed/deleted
 129         C::     modified/changed
 130         K::     to be killed
 131         ?::     other
 132 --
 133
 134 -v::
 135         Similar to `-t`, but use lowercase letters for files
 136         that are marked as 'assume unchanged' (see
 137         linkgit:git-update-index[1]).
 138
 139 -f::
 140         Similar to `-t`, but use lowercase letters for files
 141         that are marked as 'fsmonitor valid' (see
 142         linkgit:git-update-index[1]).
 143
 144 --full-name::
 145         When run from a subdirectory, the command usually
 146         outputs paths relative to the current directory.  This
 147         option forces paths to be output relative to the project
 148         top directory.
 149
 150 --recurse-submodules::
 151         Recursively calls ls-files on each active submodule in the repository.
 152         Currently there is only support for the --cached mode.
 153
 154 --abbrev[=<n>]::
 155         Instead of showing the full 40-byte hexadecimal object
 156         lines, show the shortest prefix that is at least '<n>'
 157         hexdigits long that uniquely refers the object.
 158         Non default number of digits can be specified with --abbrev=<n>.
 159
 160 --debug::
 161         After each line that describes a file, add more data about its
 162         cache entry.  This is intended to show as much information as
 163         possible for manual inspection; the exact format may change at
 164         any time.
 165
 166 --eol::
 167         Show <eolinfo> and <eolattr> of files.
 168         <eolinfo> is the file content identification used by Git when
 169         the "text" attribute is "auto" (or not set and core.autocrlf is not false).
 170         <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "".
 171 +
 172 "" means the file is not a regular file, it is not in the index or
 173 not accessible in the working tree.
 174 +
 175 <eolattr> is the attribute that is used when checking out or committing,
 176 it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
 177 Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
 178 +
 179 Both the <eolinfo> in the index ("i/<eolinfo>")
 180 and in the working tree ("w/<eolinfo>") are shown for regular files,
 181 followed by the  ("attr/<eolattr>").
 182
 183 \--::
 184         Do not interpret any more arguments as options.
 185
 186 <file>::
 187         Files to show. If no files are given all files which match the other
 188         specified criteria are shown.
 189
 190 OUTPUT
 191 ------
 192 'git ls-files' just outputs the filenames unless `--stage` is specified in
 193 which case it outputs:
 194
 195         [<tag> ]<mode> <object> <stage> <file>
 196
 197 'git ls-files --eol' will show
 198         i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
 199
 200 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
 201 detailed information on unmerged paths.
 202
 203 For an unmerged path, instead of recording a single mode/SHA-1 pair,
 204 the index records up to three such pairs; one from tree O in stage
 205 1, A in stage 2, and B in stage 3.  This information can be used by
 206 the user (or the porcelain) to see what should eventually be recorded at the
 207 path. (see linkgit:git-read-tree[1] for more information on state)
 208
 209 Without the `-z` option, pathnames with "unusual" characters are
 210 quoted as explained for the configuration variable `core.quotePath`
 211 (see linkgit:git-config[1]).  Using `-z` the filename is output
 212 verbatim and the line is terminated by a NUL byte.
 213
 214
 215 EXCLUDE PATTERNS
 216 ----------------
 217
 218 'git ls-files' can use a list of "exclude patterns" when
 219 traversing the directory tree and finding files to show when the
 220 flags --others or --ignored are specified.  linkgit:gitignore[5]
 221 specifies the format of exclude patterns.
 222
 223 These exclude patterns come from these places, in order:
 224
 225   1. The command-line flag --exclude=<pattern> specifies a
 226      single pattern.  Patterns are ordered in the same order
 227      they appear in the command line.
 228
 229   2. The command-line flag --exclude-from=<file> specifies a
 230      file containing a list of patterns.  Patterns are ordered
 231      in the same order they appear in the file.
 232
 233   3. The command-line flag --exclude-per-directory=<name> specifies
 234      a name of the file in each directory 'git ls-files'
 235      examines, normally `.gitignore`.  Files in deeper
 236      directories take precedence.  Patterns are ordered in the
 237      same order they appear in the files.
 238
 239 A pattern specified on the command line with --exclude or read
 240 from the file specified with --exclude-from is relative to the
 241 top of the directory tree.  A pattern read from a file specified
 242 by --exclude-per-directory is relative to the directory that the
 243 pattern file appears in.
 244
 245 SEE ALSO
 246 --------
 247 linkgit:git-read-tree[1], linkgit:gitignore[5]
 248
 249 GIT
 250 ---
 251 Part of the linkgit:git[1] suite