Documentation / git-ls-files.txton commit wt-status.h: drop stdio.h include (7a06fb0)
   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+
 121--
 122This option identifies the file status with the following tags (followed by
 123a 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 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 only a partial prefix.
 157        Non default number of digits can be specified with --abbrev=<n>.
 158
 159--debug::
 160        After each line that describes a file, add more data about its
 161        cache entry.  This is intended to show as much information as
 162        possible for manual inspection; the exact format may change at
 163        any time.
 164
 165--eol::
 166        Show <eolinfo> and <eolattr> of files.
 167        <eolinfo> is the file content identification used by Git when
 168        the "text" attribute is "auto" (or not set and core.autocrlf is not false).
 169        <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "".
 170+
 171"" means the file is not a regular file, it is not in the index or
 172not accessible in the working tree.
 173+
 174<eolattr> is the attribute that is used when checking out or committing,
 175it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
 176Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
 177+
 178Both the <eolinfo> in the index ("i/<eolinfo>")
 179and in the working tree ("w/<eolinfo>") are shown for regular files,
 180followed by the  ("attr/<eolattr>").
 181
 182\--::
 183        Do not interpret any more arguments as options.
 184
 185<file>::
 186        Files to show. If no files are given all files which match the other
 187        specified criteria are shown.
 188
 189OUTPUT
 190------
 191'git ls-files' just outputs the filenames unless `--stage` is specified in
 192which case it outputs:
 193
 194        [<tag> ]<mode> <object> <stage> <file>
 195
 196'git ls-files --eol' will show
 197        i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
 198
 199'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
 200detailed information on unmerged paths.
 201
 202For an unmerged path, instead of recording a single mode/SHA-1 pair,
 203the index records up to three such pairs; one from tree O in stage
 2041, A in stage 2, and B in stage 3.  This information can be used by
 205the user (or the porcelain) to see what should eventually be recorded at the
 206path. (see linkgit:git-read-tree[1] for more information on state)
 207
 208Without the `-z` option, pathnames with "unusual" characters are
 209quoted as explained for the configuration variable `core.quotePath`
 210(see linkgit:git-config[1]).  Using `-z` the filename is output
 211verbatim and the line is terminated by a NUL byte.
 212
 213
 214EXCLUDE PATTERNS
 215----------------
 216
 217'git ls-files' can use a list of "exclude patterns" when
 218traversing the directory tree and finding files to show when the
 219flags --others or --ignored are specified.  linkgit:gitignore[5]
 220specifies the format of exclude patterns.
 221
 222These exclude patterns come from these places, in order:
 223
 224  1. The command-line flag --exclude=<pattern> specifies a
 225     single pattern.  Patterns are ordered in the same order
 226     they appear in the command line.
 227
 228  2. The command-line flag --exclude-from=<file> specifies a
 229     file containing a list of patterns.  Patterns are ordered
 230     in the same order they appear in the file.
 231
 232  3. The command-line flag --exclude-per-directory=<name> specifies
 233     a name of the file in each directory 'git ls-files'
 234     examines, normally `.gitignore`.  Files in deeper
 235     directories take precedence.  Patterns are ordered in the
 236     same order they appear in the files.
 237
 238A pattern specified on the command line with --exclude or read
 239from the file specified with --exclude-from is relative to the
 240top of the directory tree.  A pattern read from a file specified
 241by --exclude-per-directory is relative to the directory that the
 242pattern file appears in.
 243
 244SEE ALSO
 245--------
 246linkgit:git-read-tree[1], linkgit:gitignore[5]
 247
 248GIT
 249---
 250Part of the linkgit:git[1] suite