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 --
 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 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
 172 not accessible in the working tree.
 173 +
 174 <eolattr> is the attribute that is used when checking out or committing,
 175 it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
 176 Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
 177 +
 178 Both the <eolinfo> in the index ("i/<eolinfo>")
 179 and in the working tree ("w/<eolinfo>") are shown for regular files,
 180 followed 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
 189 OUTPUT
 190 ------
 191 'git ls-files' just outputs the filenames unless `--stage` is specified in
 192 which 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
 200 detailed information on unmerged paths.
 201
 202 For an unmerged path, instead of recording a single mode/SHA-1 pair,
 203 the index records up to three such pairs; one from tree O in stage
 204 1, A in stage 2, and B in stage 3.  This information can be used by
 205 the user (or the porcelain) to see what should eventually be recorded at the
 206 path. (see linkgit:git-read-tree[1] for more information on state)
 207
 208 Without the `-z` option, pathnames with "unusual" characters are
 209 quoted as explained for the configuration variable `core.quotePath`
 210 (see linkgit:git-config[1]).  Using `-z` the filename is output
 211 verbatim and the line is terminated by a NUL byte.
 212
 213
 214 EXCLUDE PATTERNS
 215 ----------------
 216
 217 'git ls-files' can use a list of "exclude patterns" when
 218 traversing the directory tree and finding files to show when the
 219 flags --others or --ignored are specified.  linkgit:gitignore[5]
 220 specifies the format of exclude patterns.
 221
 222 These 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
 238 A pattern specified on the command line with --exclude or read
 239 from the file specified with --exclude-from is relative to the
 240 top of the directory tree.  A pattern read from a file specified
 241 by --exclude-per-directory is relative to the directory that the
 242 pattern file appears in.
 243
 244 SEE ALSO
 245 --------
 246 linkgit:git-read-tree[1], linkgit:gitignore[5]
 247
 248 GIT
 249 ---
 250 Part of the linkgit:git[1] suite