git.oblomov.eu Git - git/blob - 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[=<n>]] [--] [<file>...]
  23
  24 DESCRIPTION
  25 -----------
  26 This merges the file listing in the index with the actual working
  27 directory list, and shows different combinations of the 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. Standard ignore rules are not automatically activated,
  56         therefore at least one of the `--exclude*` options is required.
  57
  58 -s::
  59 --stage::
  60         Show staged contents' mode bits, object name and stage number in the output.
  61
  62 --directory::
  63         If a whole directory is classified as "other", show just its
  64         name (with a trailing slash) and not its whole contents.
  65
  66 --no-empty-directory::
  67         Do not list empty directories. Has no effect without --directory.
  68
  69 -u::
  70 --unmerged::
  71         Show unmerged files in the output (forces --stage)
  72
  73 -k::
  74 --killed::
  75         Show files on the filesystem that need to be removed due
  76         to file/directory conflicts for checkout-index to
  77         succeed.
  78
  79 -z::
  80         \0 line termination on output and do not quote filenames.
  81         See OUTPUT below for more information.
  82
  83 -x <pattern>::
  84 --exclude=<pattern>::
  85         Skip untracked files matching pattern.
  86         Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS
  87         below for more information.
  88
  89 -X <file>::
  90 --exclude-from=<file>::
  91         Read exclude patterns from <file>; 1 per line.
  92
  93 --exclude-per-directory=<file>::
  94         Read additional exclude patterns that apply only to the
  95         directory and its subdirectories in <file>.
  96
  97 --exclude-standard::
  98         Add the standard Git exclusions: .git/info/exclude, .gitignore
  99         in each directory, and the user's global exclusion file.
 100
 101 --error-unmatch::
 102         If any <file> does not appear in the index, treat this as an
 103         error (return 1).
 104
 105 --with-tree=<tree-ish>::
 106         When using --error-unmatch to expand the user supplied
 107         <file> (i.e. path pattern) arguments to paths, pretend
 108         that paths which were removed in the index since the
 109         named <tree-ish> are still present.  Using this option
 110         with `-s` or `-u` options does not make any sense.
 111
 112 -t::
 113         This feature is semi-deprecated. For scripting purpose,
 114         linkgit:git-status[1] `--porcelain` and
 115         linkgit:git-diff-files[1] `--name-status` are almost always
 116         superior alternatives, and users should look at
 117         linkgit:git-status[1] `--short` or linkgit:git-diff[1]
 118         `--name-status` for more user-friendly alternatives.
 119 +
 120 --
 121 This option identifies the file status with the following tags (followed by
 122 a 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
 133 -v::
 134         Similar to `-t`, but use lowercase letters for files
 135         that are marked as 'assume unchanged' (see
 136         linkgit:git-update-index[1]).
 137
 138 -f::
 139         Similar to `-t`, but use lowercase letters for files
 140         that are marked as 'fsmonitor valid' (see
 141         linkgit:git-update-index[1]).
 142
 143 --full-name::
 144         When run from a subdirectory, the command usually
 145         outputs paths relative to the current directory.  This
 146         option forces paths to be output relative to the project
 147         top directory.
 148
 149 --recurse-submodules::
 150         Recursively calls ls-files on each active submodule in the repository.
 151         Currently there is only support for the --cached mode.
 152
 153 --abbrev[=<n>]::
 154         Instead of showing the full 40-byte hexadecimal object
 155         lines, show the shortest prefix that is at least '<n>'
 156         hexdigits long that uniquely refers the object.
 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