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 accessable 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 Note: Currently Git does not support "text=auto eol=lf" or "text=auto eol=crlf",
 163 that may change in the future.
 164 +
 165 Both the <eolinfo> in the index ("i/<eolinfo>")
 166 and in the working tree ("w/<eolinfo>") are shown for regular files,
 167 followed by the  ("attr/<eolattr>").
 168
 169 \--::
 170         Do not interpret any more arguments as options.
 171
 172 <file>::
 173         Files to show. If no files are given all files which match the other
 174         specified criteria are shown.
 175
 176 Output
 177 ------
 178 'git ls-files' just outputs the filenames unless '--stage' is specified in
 179 which case it outputs:
 180
 181         [<tag> ]<mode> <object> <stage> <file>
 182
 183 'git ls-files --eol' will show
 184         i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
 185
 186 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
 187 detailed information on unmerged paths.
 188
 189 For an unmerged path, instead of recording a single mode/SHA-1 pair,
 190 the index records up to three such pairs; one from tree O in stage
 191 1, A in stage 2, and B in stage 3.  This information can be used by
 192 the user (or the porcelain) to see what should eventually be recorded at the
 193 path. (see linkgit:git-read-tree[1] for more information on state)
 194
 195 When `-z` option is not used, TAB, LF, and backslash characters
 196 in pathnames are represented as `\t`, `\n`, and `\\`,
 197 respectively.
 198
 199
 200 Exclude Patterns
 201 ----------------
 202
 203 'git ls-files' can use a list of "exclude patterns" when
 204 traversing the directory tree and finding files to show when the
 205 flags --others or --ignored are specified.  linkgit:gitignore[5]
 206 specifies the format of exclude patterns.
 207
 208 These exclude patterns come from these places, in order:
 209
 210   1. The command-line flag --exclude=<pattern> specifies a
 211      single pattern.  Patterns are ordered in the same order
 212      they appear in the command line.
 213
 214   2. The command-line flag --exclude-from=<file> specifies a
 215      file containing a list of patterns.  Patterns are ordered
 216      in the same order they appear in the file.
 217
 218   3. The command-line flag --exclude-per-directory=<name> specifies
 219      a name of the file in each directory 'git ls-files'
 220      examines, normally `.gitignore`.  Files in deeper
 221      directories take precedence.  Patterns are ordered in the
 222      same order they appear in the files.
 223
 224 A pattern specified on the command line with --exclude or read
 225 from the file specified with --exclude-from is relative to the
 226 top of the directory tree.  A pattern read from a file specified
 227 by --exclude-per-directory is relative to the directory that the
 228 pattern file appears in.
 229
 230 SEE ALSO
 231 --------
 232 linkgit:git-read-tree[1], linkgit:gitignore[5]
 233
 234 GIT
 235 ---
 236 Part of the linkgit:git[1] suite