Documentation / git-ls-files.txton commit chainlint: fix for core.autocrlf=true (1ce2b45)
   1git-ls-files(1)
   2===============
   3
   4NAME
   5----
   6git-ls-files - Show information about files in the index and the working tree
   7
   8
   9SYNOPSIS
  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
  24DESCRIPTION
  25-----------
  26This merges the file listing in the directory cache index with the
  27actual working directory list, and shows different combinations of the
  28two.
  29
  30One or more of the options below may be used to determine the files
  31shown:
  32
  33OPTIONS
  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+
 121This option identifies the file status with the following tags (followed by
 122a 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
 170not accessible in the working tree.
 171+
 172<eolattr> is the attribute that is used when checking out or committing,
 173it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
 174Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
 175+
 176Both the <eolinfo> in the index ("i/<eolinfo>")
 177and in the working tree ("w/<eolinfo>") are shown for regular files,
 178followed 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
 187OUTPUT
 188------
 189'git ls-files' just outputs the filenames unless `--stage` is specified in
 190which 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
 198detailed information on unmerged paths.
 199
 200For an unmerged path, instead of recording a single mode/SHA-1 pair,
 201the index records up to three such pairs; one from tree O in stage
 2021, A in stage 2, and B in stage 3.  This information can be used by
 203the user (or the porcelain) to see what should eventually be recorded at the
 204path. (see linkgit:git-read-tree[1] for more information on state)
 205
 206Without the `-z` option, pathnames with "unusual" characters are
 207quoted as explained for the configuration variable `core.quotePath`
 208(see linkgit:git-config[1]).  Using `-z` the filename is output
 209verbatim and the line is terminated by a NUL byte.
 210
 211
 212EXCLUDE PATTERNS
 213----------------
 214
 215'git ls-files' can use a list of "exclude patterns" when
 216traversing the directory tree and finding files to show when the
 217flags --others or --ignored are specified.  linkgit:gitignore[5]
 218specifies the format of exclude patterns.
 219
 220These 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
 236A pattern specified on the command line with --exclude or read
 237from the file specified with --exclude-from is relative to the
 238top of the directory tree.  A pattern read from a file specified
 239by --exclude-per-directory is relative to the directory that the
 240pattern file appears in.
 241
 242SEE ALSO
 243--------
 244linkgit:git-read-tree[1], linkgit:gitignore[5]
 245
 246GIT
 247---
 248Part of the linkgit:git[1] suite