Merge branch 'rs/midx-use-strvec-pushf'
[alt-git.git] / Documentation / git-ls-files.txt
blobd08c7da8f495b3e19fb763535ff742585da9ce3e
1 git-ls-files(1)
2 ===============
4 NAME
5 ----
6 git-ls-files - Show information about files in the index and the working tree
9 SYNOPSIS
10 --------
11 [verse]
12 'git ls-files' [-z] [-t] [-v] [-f]
13                 [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
14                 [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
15                 [--resolve-undo]
16                 [--directory [--no-empty-directory]] [--eol]
17                 [--deduplicate]
18                 [-x <pattern>|--exclude=<pattern>]
19                 [-X <file>|--exclude-from=<file>]
20                 [--exclude-per-directory=<file>]
21                 [--exclude-standard]
22                 [--error-unmatch] [--with-tree=<tree-ish>]
23                 [--full-name] [--recurse-submodules]
24                 [--abbrev[=<n>]] [--format=<format>] [--] [<file>...]
26 DESCRIPTION
27 -----------
28 This command merges the file listing in the index with the actual working
29 directory list, and shows different combinations of the two.
31 Several flags can be used to determine which files are
32 shown, and each file may be printed multiple times if there are
33 multiple entries in the index or if multiple statuses are applicable for
34 the relevant file selection options.
36 OPTIONS
37 -------
38 -c::
39 --cached::
40         Show all files cached in Git's index, i.e. all tracked files.
41         (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo
42         options are specified.)
44 -d::
45 --deleted::
46         Show files with an unstaged deletion
48 -m::
49 --modified::
50         Show files with an unstaged modification (note that an unstaged
51         deletion also counts as an unstaged modification)
53 -o::
54 --others::
55         Show other (i.e. untracked) files in the output
57 -i::
58 --ignored::
59         Show only ignored files in the output.  Must be used with
60         either an explicit '-c' or '-o'.  When showing files in the
61         index (i.e. when used with '-c'), print only those files
62         matching an exclude pattern.  When showing "other" files
63         (i.e. when used with '-o'), show only those matched by an
64         exclude pattern.  Standard ignore rules are not automatically
65         activated; therefore, at least one of the `--exclude*` options
66         is required.
68 -s::
69 --stage::
70         Show staged contents' mode bits, object name and stage number in the output.
72 --directory::
73         If a whole directory is classified as "other", show just its
74         name (with a trailing slash) and not its whole contents.
75         Has no effect without -o/--others.
77 --no-empty-directory::
78         Do not list empty directories. Has no effect without --directory.
80 -u::
81 --unmerged::
82         Show information about unmerged files in the output, but do
83         not show any other tracked files (forces --stage, overrides
84         --cached).
86 -k::
87 --killed::
88         Show untracked files on the filesystem that need to be removed
89         due to file/directory conflicts for tracked files to be able to
90         be written to the filesystem.
92 --resolve-undo::
93         Show files having resolve-undo information in the index
94         together with their resolve-undo information.  (resolve-undo
95         information is what is used to implement "git checkout -m
96         $PATH", i.e. to recreate merge conflicts that were
97         accidentally resolved)
99 -z::
100         \0 line termination on output and do not quote filenames.
101         See OUTPUT below for more information.
103 --deduplicate::
104         When only filenames are shown, suppress duplicates that may
105         come from having multiple stages during a merge, or giving
106         `--deleted` and `--modified` option at the same time.
107         When any of the `-t`, `--unmerged`, or `--stage` option is
108         in use, this option has no effect.
110 -x <pattern>::
111 --exclude=<pattern>::
112         Skip untracked files matching pattern.
113         Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS
114         below for more information.
116 -X <file>::
117 --exclude-from=<file>::
118         Read exclude patterns from <file>; 1 per line.
120 --exclude-per-directory=<file>::
121         Read additional exclude patterns that apply only to the
122         directory and its subdirectories in <file>.  If you are
123         trying to emulate the way Porcelain commands work, using
124         the `--exclude-standard` option instead is easier and more
125         thorough.
127 --exclude-standard::
128         Add the standard Git exclusions: .git/info/exclude, .gitignore
129         in each directory, and the user's global exclusion file.
131 --error-unmatch::
132         If any <file> does not appear in the index, treat this as an
133         error (return 1).
135 --with-tree=<tree-ish>::
136         When using --error-unmatch to expand the user supplied
137         <file> (i.e. path pattern) arguments to paths, pretend
138         that paths which were removed in the index since the
139         named <tree-ish> are still present.  Using this option
140         with `-s` or `-u` options does not make any sense.
142 -t::
143         Show status tags together with filenames.  Note that for
144         scripting purposes, linkgit:git-status[1] `--porcelain` and
145         linkgit:git-diff-files[1] `--name-status` are almost always
146         superior alternatives; users should look at
147         linkgit:git-status[1] `--short` or linkgit:git-diff[1]
148         `--name-status` for more user-friendly alternatives.
151 This option provides a reason for showing each filename, in the form
152 of a status tag (which is followed by a space and then the filename).
153 The status tags are all single characters from the following list:
155         H::     tracked file that is not either unmerged or skip-worktree
156         S::     tracked file that is skip-worktree
157         M::     tracked file that is unmerged
158         R::     tracked file with unstaged removal/deletion
159         C::     tracked file with unstaged modification/change
160         K::     untracked paths which are part of file/directory conflicts
161                 which prevent checking out tracked files
162         ?::     untracked file
163         U::     file with resolve-undo information
166 -v::
167         Similar to `-t`, but use lowercase letters for files
168         that are marked as 'assume unchanged' (see
169         linkgit:git-update-index[1]).
171 -f::
172         Similar to `-t`, but use lowercase letters for files
173         that are marked as 'fsmonitor valid' (see
174         linkgit:git-update-index[1]).
176 --full-name::
177         When run from a subdirectory, the command usually
178         outputs paths relative to the current directory.  This
179         option forces paths to be output relative to the project
180         top directory.
182 --recurse-submodules::
183         Recursively calls ls-files on each active submodule in the repository.
184         Currently there is only support for the --cached and --stage modes.
186 --abbrev[=<n>]::
187         Instead of showing the full 40-byte hexadecimal object
188         lines, show the shortest prefix that is at least '<n>'
189         hexdigits long that uniquely refers the object.
190         Non default number of digits can be specified with --abbrev=<n>.
192 --debug::
193         After each line that describes a file, add more data about its
194         cache entry.  This is intended to show as much information as
195         possible for manual inspection; the exact format may change at
196         any time.
198 --eol::
199         Show <eolinfo> and <eolattr> of files.
200         <eolinfo> is the file content identification used by Git when
201         the "text" attribute is "auto" (or not set and core.autocrlf is not false).
202         <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "".
204 "" means the file is not a regular file, it is not in the index or
205 not accessible in the working tree.
207 <eolattr> is the attribute that is used when checking out or committing,
208 it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
209 Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
211 Both the <eolinfo> in the index ("i/<eolinfo>")
212 and in the working tree ("w/<eolinfo>") are shown for regular files,
213 followed by the  ("attr/<eolattr>").
215 --sparse::
216         If the index is sparse, show the sparse directories without expanding
217         to the contained files. Sparse directories will be shown with a
218         trailing slash, such as "x/" for a sparse directory "x".
220 --format=<format>::
221         A string that interpolates `%(fieldname)` from the result being shown.
222         It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits
223         interpolates to character with hex code `xx`; for example `%00`
224         interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF).
225         --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo`
226         and `--eol`.
227 \--::
228         Do not interpret any more arguments as options.
230 <file>::
231         Files to show. If no files are given all files which match the other
232         specified criteria are shown.
234 OUTPUT
235 ------
236 'git ls-files' just outputs the filenames unless `--stage` is specified in
237 which case it outputs:
239         [<tag> ]<mode> <object> <stage> <file>
241 'git ls-files --eol' will show
242         i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
244 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
245 detailed information on unmerged paths.
247 For an unmerged path, instead of recording a single mode/SHA-1 pair,
248 the index records up to three such pairs; one from tree O in stage
249 1, A in stage 2, and B in stage 3.  This information can be used by
250 the user (or the porcelain) to see what should eventually be recorded at the
251 path. (see linkgit:git-read-tree[1] for more information on state)
253 Without the `-z` option, pathnames with "unusual" characters are
254 quoted as explained for the configuration variable `core.quotePath`
255 (see linkgit:git-config[1]).  Using `-z` the filename is output
256 verbatim and the line is terminated by a NUL byte.
258 It is possible to print in a custom format by using the `--format`
259 option, which is able to interpolate different fields using
260 a `%(fieldname)` notation. For example, if you only care about the
261 "objectname" and "path" fields, you can execute with a specific
262 "--format" like
264         git ls-files --format='%(objectname) %(path)'
266 FIELD NAMES
267 -----------
268 The way each path is shown can be customized by using the
269 `--format=<format>` option, where the %(fieldname) in the
270 <format> string for various aspects of the index entry are
271 interpolated.  The following "fieldname" are understood:
273 objectmode::
274         The mode of the file which is recorded in the index.
275 objecttype::
276         The object type of the file which is recorded in the index.
277 objectname::
278         The name of the file which is recorded in the index.
279 objectsize[:padded]::
280         The object size of the file which is recorded in the index
281         ("-" if the object is a `commit` or `tree`).
282         It also supports a padded format of size with "%(objectsize:padded)".
283 stage::
284         The stage of the file which is recorded in the index.
285 eolinfo:index::
286 eolinfo:worktree::
287         The <eolinfo> (see the description of the `--eol` option) of
288         the contents in the index or in the worktree for the path.
289 eolattr::
290         The <eolattr> (see the description of the `--eol` option)
291         that applies to the path.
292 path::
293         The pathname of the file which is recorded in the index.
295 EXCLUDE PATTERNS
296 ----------------
298 'git ls-files' can use a list of "exclude patterns" when
299 traversing the directory tree and finding files to show when the
300 flags --others or --ignored are specified.  linkgit:gitignore[5]
301 specifies the format of exclude patterns.
303 These exclude patterns can be specified from the following places,
304 in order:
306   1. The command-line flag --exclude=<pattern> specifies a
307      single pattern.  Patterns are ordered in the same order
308      they appear in the command line.
310   2. The command-line flag --exclude-from=<file> specifies a
311      file containing a list of patterns.  Patterns are ordered
312      in the same order they appear in the file.
314   3. The command-line flag --exclude-per-directory=<name> specifies
315      a name of the file in each directory 'git ls-files'
316      examines, normally `.gitignore`.  Files in deeper
317      directories take precedence.  Patterns are ordered in the
318      same order they appear in the files.
320 A pattern specified on the command line with --exclude or read
321 from the file specified with --exclude-from is relative to the
322 top of the directory tree.  A pattern read from a file specified
323 by --exclude-per-directory is relative to the directory that the
324 pattern file appears in.
326 Generally, you should be able to use `--exclude-standard` when you
327 want the exclude rules applied the same way as what Porcelain
328 commands do.  To emulate what `--exclude-standard` specifies, you
329 can give `--exclude-per-directory=.gitignore`, and then specify:
331   1. The file specified by the `core.excludesfile` configuration
332      variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file.
334   2. The `$GIT_DIR/info/exclude` file.
336 via the `--exclude-from=` option.
338 SEE ALSO
339 --------
340 linkgit:git-read-tree[1], linkgit:gitignore[5]
344 Part of the linkgit:git[1] suite