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