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