freshlybakedca.ke
Git fork
1git-ls-files(1)
2===============
3
4NAME
5----
6git-ls-files - Show information about files in the index and the working tree
7
8
9SYNOPSIS
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>...]
25
26DESCRIPTION
27-----------
28This command merges the file listing in the index with the actual working
29directory list, and shows different combinations of the two.
30
31Several flags can be used to determine which files are
32shown, and each file may be printed multiple times if there are
33multiple entries in the index or if multiple statuses are applicable for
34the relevant file selection options.
35
36OPTIONS
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.)
43
44-d::
45--deleted::
46 Show files with an unstaged deletion
47
48-m::
49--modified::
50 Show files with an unstaged modification (note that an unstaged
51 deletion also counts as an unstaged modification)
52
53-o::
54--others::
55 Show other (i.e. untracked) files in the output
56
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.
67
68-s::
69--stage::
70 Show staged contents' mode bits, object name and stage number in the output.
71
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.
76
77--no-empty-directory::
78 Do not list empty directories. Has no effect without --directory.
79
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).
85
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.
91
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)
98
99-z::
100 \0 line termination on output and do not quote filenames.
101 See OUTPUT below for more information.
102
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.
109
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.
115
116-X <file>::
117--exclude-from=<file>::
118 Read exclude patterns from <file>; 1 per line.
119
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.
126
127--exclude-standard::
128 Add the standard Git exclusions: .git/info/exclude, .gitignore
129 in each directory, and the user's global exclusion file.
130
131--error-unmatch::
132 If any <file> does not appear in the index, treat this as an
133 error (return 1).
134
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.
141
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.
149+
150--
151This option provides a reason for showing each filename, in the form
152of a status tag (which is followed by a space and then the filename).
153The status tags are all single characters from the following list:
154
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
164--
165
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]).
170
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]).
175
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.
181
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.
185
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>.
191
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.
197
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 "".
203+
204"" means the file is not a regular file, it is not in the index or
205not accessible in the working tree.
206+
207<eolattr> is the attribute that is used when checking out or committing,
208it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
209Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
210+
211Both the <eolinfo> in the index ("i/<eolinfo>")
212and in the working tree ("w/<eolinfo>") are shown for regular files,
213followed by the ("attr/<eolattr>").
214
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".
219
220--format=<format>::
221 A string that interpolates `%(fieldname)` from the result being shown.
222 It also interpolates `%%` to `%`, and `%xXX` where `XX` are hex digits
223 interpolates to character with hex code `XX`; for example `%x00`
224 interpolates to `\0` (NUL), `%x09` to `\t` (TAB) and %x0a 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.
229
230<file>::
231 Files to show. If no files are given all files which match the other
232 specified criteria are shown.
233
234OUTPUT
235------
236'git ls-files' just outputs the filenames unless `--stage` is specified in
237which case it outputs:
238
239 [<tag> ]<mode> <object> <stage> <file>
240
241'git ls-files --eol' will show
242 i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
243
244'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
245detailed information on unmerged paths.
246
247For an unmerged path, instead of recording a single mode/SHA-1 pair,
248the index records up to three such pairs; one from tree O in stage
2491, A in stage 2, and B in stage 3. This information can be used by
250the user (or the porcelain) to see what should eventually be recorded at the
251path. (see linkgit:git-read-tree[1] for more information on state)
252
253Without the `-z` option, pathnames with "unusual" characters are
254quoted as explained for the configuration variable `core.quotePath`
255(see linkgit:git-config[1]). Using `-z` the filename is output
256verbatim and the line is terminated by a NUL byte.
257
258It is possible to print in a custom format by using the `--format`
259option, which is able to interpolate different fields using
260a `%(fieldname)` notation. For example, if you only care about the
261"objectname" and "path" fields, you can execute with a specific
262"--format" like
263
264 git ls-files --format='%(objectname) %(path)'
265
266FIELD NAMES
267-----------
268The 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
271interpolated. The following "fieldname" are understood:
272
273objectmode::
274 The mode of the file which is recorded in the index.
275objecttype::
276 The object type of the file which is recorded in the index.
277objectname::
278 The name of the file which is recorded in the index.
279objectsize[: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)".
283stage::
284 The stage of the file which is recorded in the index.
285eolinfo:index::
286eolinfo: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.
289eolattr::
290 The <eolattr> (see the description of the `--eol` option)
291 that applies to the path.
292path::
293 The pathname of the file which is recorded in the index.
294
295EXCLUDE PATTERNS
296----------------
297
298'git ls-files' can use a list of "exclude patterns" when
299traversing the directory tree and finding files to show when the
300flags --others or --ignored are specified. linkgit:gitignore[5]
301specifies the format of exclude patterns.
302
303These exclude patterns can be specified from the following places,
304in order:
305
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.
309
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.
313
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.
319
320A pattern specified on the command line with --exclude or read
321from the file specified with --exclude-from is relative to the
322top of the directory tree. A pattern read from a file specified
323by --exclude-per-directory is relative to the directory that the
324pattern file appears in.
325
326Generally, you should be able to use `--exclude-standard` when you
327want the exclude rules applied the same way as what Porcelain
328commands do. To emulate what `--exclude-standard` specifies, you
329can give `--exclude-per-directory=.gitignore`, and then specify:
330
331 1. The file specified by the `core.excludesfile` configuration
332 variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file.
333
334 2. The `$GIT_DIR/info/exclude` file.
335
336via the `--exclude-from=` option.
337
338SEE ALSO
339--------
340linkgit:git-read-tree[1], linkgit:gitignore[5]
341
342GIT
343---
344Part of the linkgit:git[1] suite