6 git-ls-files - Show information about files in the index and the working tree
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]
16 [--directory [--no-empty-directory]] [--eol]
18 [-x <pattern>|--exclude=<pattern>]
19 [-X <file>|--exclude-from=<file>]
20 [--exclude-per-directory=<file>]
22 [--error-unmatch] [--with-tree=<tree-ish>]
23 [--full-name] [--recurse-submodules]
24 [--abbrev[=<n>]] [--format=<format>] [--] [<file>...]
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.
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.)
46 Show files with an unstaged deletion
50 Show files with an unstaged modification (note that an unstaged
51 deletion also counts as an unstaged modification)
55 Show other (i.e. untracked) files in the output
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
70 Show staged contents' mode bits, object name and stage number in the output.
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.
82 Show information about unmerged files in the output, but do
83 not show any other tracked files (forces --stage, overrides
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.
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)
100 \0 line termination on output and do not quote filenames.
101 See OUTPUT below for more information.
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.
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.
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
128 Add the standard Git exclusions: .git/info/exclude, .gitignore
129 in each directory, and the user's global exclusion file.
132 If any <file> does not appear in the index, treat this as an
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.
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
163 U:: file with resolve-undo information
167 Similar to `-t`, but use lowercase letters for files
168 that are marked as 'assume unchanged' (see
169 linkgit:git-update-index[1]).
172 Similar to `-t`, but use lowercase letters for files
173 that are marked as 'fsmonitor valid' (see
174 linkgit:git-update-index[1]).
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
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.
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>.
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
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>").
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".
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`
228 Do not interpret any more arguments as options.
231 Files to show. If no files are given all files which match the other
232 specified criteria are shown.
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
264 git ls-files --format='%(objectname) %(path)'
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:
274 The mode of the file which is recorded in the index.
276 The object type of the file which is recorded in the index.
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)".
284 The stage of the file which is recorded in the index.
287 The <eolinfo> (see the description of the `--eol` option) of
288 the contents in the index or in the worktree for the path.
290 The <eolattr> (see the description of the `--eol` option)
291 that applies to the path.
293 The pathname of the file which is recorded in the index.
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,
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.
340 linkgit:git-read-tree[1], linkgit:gitignore[5]
344 Part of the linkgit:git[1] suite