| blob | 642267fb1309e63a3625a3f5520387f398984231 |
1 '\" t
2 .\" Title: git-ls-files
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2024-01-26
6 .\" Manual: Git Manual
7 .\" Source: Git 2.43.0.440.gb50a608ba2
8 .\" Language: English
9 .\"
10 .TH "GIT\-LS\-FILES" "1" "2024\-01\-26" "Git 2\&.43\&.0\&.440\&.gb50a60" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-ls-files \- Show information about files in the index and the working tree
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit ls\-files\fR [\-z] [\-t] [\-v] [\-f]
36 [\-c|\-\-cached] [\-d|\-\-deleted] [\-o|\-\-others] [\-i|\-\-ignored]
37 [\-s|\-\-stage] [\-u|\-\-unmerged] [\-k|\-\-killed] [\-m|\-\-modified]
38 [\-\-resolve\-undo]
39 [\-\-directory [\-\-no\-empty\-directory]] [\-\-eol]
40 [\-\-deduplicate]
41 [\-x <pattern>|\-\-exclude=<pattern>]
42 [\-X <file>|\-\-exclude\-from=<file>]
43 [\-\-exclude\-per\-directory=<file>]
44 [\-\-exclude\-standard]
45 [\-\-error\-unmatch] [\-\-with\-tree=<tree\-ish>]
46 [\-\-full\-name] [\-\-recurse\-submodules]
47 [\-\-abbrev[=<n>]] [\-\-format=<format>] [\-\-] [<file>\&...]
48 .fi
49 .sp
50 .SH "DESCRIPTION"
51 .sp
52 This command merges the file listing in the index with the actual working directory list, and shows different combinations of the two\&.
53 .sp
54 Several flags can be used to determine which files are shown, and each file may be printed multiple times if there are multiple entries in the index or if multiple statuses are applicable for the relevant file selection options\&.
55 .SH "OPTIONS"
56 .PP
57 \-c, \-\-cached
58 .RS 4
59 Show all files cached in Git\(cqs index, i\&.e\&. all tracked files\&. (This is the default if no \-c/\-s/\-d/\-o/\-u/\-k/\-m/\-\-resolve\-undo options are specified\&.)
60 .RE
61 .PP
62 \-d, \-\-deleted
63 .RS 4
64 Show files with an unstaged deletion
65 .RE
66 .PP
67 \-m, \-\-modified
68 .RS 4
69 Show files with an unstaged modification (note that an unstaged deletion also counts as an unstaged modification)
70 .RE
71 .PP
72 \-o, \-\-others
73 .RS 4
74 Show other (i\&.e\&. untracked) files in the output
75 .RE
76 .PP
77 \-i, \-\-ignored
78 .RS 4
79 Show only ignored files in the output\&. Must be used with either an explicit
80 \fI\-c\fR
81 or
82 \fI\-o\fR\&. When showing files in the index (i\&.e\&. when used with
83 \fI\-c\fR), print only those files matching an exclude pattern\&. When showing "other" files (i\&.e\&. when used with
84 \fI\-o\fR), show only those matched by an exclude pattern\&. Standard ignore rules are not automatically activated; therefore, at least one of the
85 \fB\-\-exclude*\fR
86 options is required\&.
87 .RE
88 .PP
89 \-s, \-\-stage
90 .RS 4
91 Show staged contents\*(Aq mode bits, object name and stage number in the output\&.
92 .RE
93 .PP
94 \-\-directory
95 .RS 4
96 If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents\&. Has no effect without \-o/\-\-others\&.
97 .RE
98 .PP
99 \-\-no\-empty\-directory
100 .RS 4
101 Do not list empty directories\&. Has no effect without \-\-directory\&.
102 .RE
103 .PP
104 \-u, \-\-unmerged
105 .RS 4
106 Show information about unmerged files in the output, but do not show any other tracked files (forces \-\-stage, overrides \-\-cached)\&.
107 .RE
108 .PP
109 \-k, \-\-killed
110 .RS 4
111 Show untracked files on the filesystem that need to be removed due to file/directory conflicts for tracked files to be able to be written to the filesystem\&.
112 .RE
113 .PP
114 \-\-resolve\-undo
115 .RS 4
116 Show files having resolve\-undo information in the index together with their resolve\-undo information\&. (resolve\-undo information is what is used to implement "git checkout \-m $PATH", i\&.e\&. to recreate merge conflicts that were accidentally resolved)
117 .RE
118 .PP
119 \-z
120 .RS 4
121 \e0 line termination on output and do not quote filenames\&. See OUTPUT below for more information\&.
122 .RE
123 .PP
124 \-\-deduplicate
125 .RS 4
126 When only filenames are shown, suppress duplicates that may come from having multiple stages during a merge, or giving
127 \fB\-\-deleted\fR
128 and
129 \fB\-\-modified\fR
130 option at the same time\&. When any of the
131 \fB\-t\fR,
132 \fB\-\-unmerged\fR, or
133 \fB\-\-stage\fR
134 option is in use, this option has no effect\&.
135 .RE
136 .PP
137 \-x <pattern>, \-\-exclude=<pattern>
138 .RS 4
139 Skip untracked files matching pattern\&. Note that pattern is a shell wildcard pattern\&. See EXCLUDE PATTERNS below for more information\&.
140 .RE
141 .PP
142 \-X <file>, \-\-exclude\-from=<file>
143 .RS 4
144 Read exclude patterns from <file>; 1 per line\&.
145 .RE
146 .PP
147 \-\-exclude\-per\-directory=<file>
148 .RS 4
149 Read additional exclude patterns that apply only to the directory and its subdirectories in <file>\&. Deprecated; use \-\-exclude\-standard instead\&.
150 .RE
151 .PP
152 \-\-exclude\-standard
153 .RS 4
154 Add the standard Git exclusions: \&.git/info/exclude, \&.gitignore in each directory, and the user\(cqs global exclusion file\&.
155 .RE
156 .PP
157 \-\-error\-unmatch
158 .RS 4
159 If any <file> does not appear in the index, treat this as an error (return 1)\&.
160 .RE
161 .PP
162 \-\-with\-tree=<tree\-ish>
163 .RS 4
164 When using \-\-error\-unmatch to expand the user supplied <file> (i\&.e\&. path pattern) arguments to paths, pretend that paths which were removed in the index since the named <tree\-ish> are still present\&. Using this option with
165 \fB\-s\fR
166 or
167 \fB\-u\fR
168 options does not make any sense\&.
169 .RE
170 .PP
171 \-t
172 .RS 4
173 Show status tags together with filenames\&. Note that for scripting purposes,
174 \fBgit-status\fR(1)
175 \fB\-\-porcelain\fR
176 and
177 \fBgit-diff-files\fR(1)
178 \fB\-\-name\-status\fR
179 are almost always superior alternatives; users should look at
180 \fBgit-status\fR(1)
181 \fB\-\-short\fR
182 or
183 \fBgit-diff\fR(1)
184 \fB\-\-name\-status\fR
185 for more user\-friendly alternatives\&.
186 .sp
187 This option provides a reason for showing each filename, in the form of a status tag (which is followed by a space and then the filename)\&. The status tags are all single characters from the following list:
188 .PP
189 H
190 .RS 4
191 tracked file that is not either unmerged or skip\-worktree
192 .RE
193 .PP
194 S
195 .RS 4
196 tracked file that is skip\-worktree
197 .RE
198 .PP
199 M
200 .RS 4
201 tracked file that is unmerged
202 .RE
203 .PP
204 R
205 .RS 4
206 tracked file with unstaged removal/deletion
207 .RE
208 .PP
209 C
210 .RS 4
211 tracked file with unstaged modification/change
212 .RE
213 .PP
214 K
215 .RS 4
216 untracked paths which are part of file/directory conflicts which prevent checking out tracked files
217 .RE
218 .PP
219 ?
220 .RS 4
221 untracked file
222 .RE
223 .PP
224 U
225 .RS 4
226 file with resolve\-undo information
227 .RE
228 .RE
229 .PP
230 \-v
231 .RS 4
232 Similar to
233 \fB\-t\fR, but use lowercase letters for files that are marked as
234 \fIassume unchanged\fR
235 (see
236 \fBgit-update-index\fR(1))\&.
237 .RE
238 .PP
239 \-f
240 .RS 4
241 Similar to
242 \fB\-t\fR, but use lowercase letters for files that are marked as
243 \fIfsmonitor valid\fR
244 (see
245 \fBgit-update-index\fR(1))\&.
246 .RE
247 .PP
248 \-\-full\-name
249 .RS 4
250 When run from a subdirectory, the command usually outputs paths relative to the current directory\&. This option forces paths to be output relative to the project top directory\&.
251 .RE
252 .PP
253 \-\-recurse\-submodules
254 .RS 4
255 Recursively calls ls\-files on each active submodule in the repository\&. Currently there is only support for the \-\-cached and \-\-stage modes\&.
256 .RE
257 .PP
258 \-\-abbrev[=<n>]
259 .RS 4
260 Instead of showing the full 40\-byte hexadecimal object lines, show the shortest prefix that is at least
261 \fI<n>\fR
262 hexdigits long that uniquely refers the object\&. Non default number of digits can be specified with \-\-abbrev=<n>\&.
263 .RE
264 .PP
265 \-\-debug
266 .RS 4
267 After each line that describes a file, add more data about its cache entry\&. This is intended to show as much information as possible for manual inspection; the exact format may change at any time\&.
268 .RE
269 .PP
270 \-\-eol
271 .RS 4
272 Show <eolinfo> and <eolattr> of files\&. <eolinfo> is the file content identification used by Git when the "text" attribute is "auto" (or not set and core\&.autocrlf is not false)\&. <eolinfo> is either "\-text", "none", "lf", "crlf", "mixed" or ""\&.
273 .sp
274 "" means the file is not a regular file, it is not in the index or not accessible in the working tree\&.
275 .sp
276 <eolattr> is the attribute that is used when checking out or committing, it is either "", "\-text", "text", "text=auto", "text eol=lf", "text eol=crlf"\&. Since Git 2\&.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported\&.
277 .sp
278 Both the <eolinfo> in the index ("i/<eolinfo>") and in the working tree ("w/<eolinfo>") are shown for regular files, followed by the ("attr/<eolattr>")\&.
279 .RE
280 .PP
281 \-\-sparse
282 .RS 4
283 If the index is sparse, show the sparse directories without expanding to the contained files\&. Sparse directories will be shown with a trailing slash, such as "x/" for a sparse directory "x"\&.
284 .RE
285 .PP
286 \-\-format=<format>
287 .RS 4
288 A string that interpolates
289 \fB%(fieldname)\fR
290 from the result being shown\&. It also interpolates
291 \fB%%\fR
292 to
293 \fB%\fR, and
294 \fB%xx\fR
295 where
296 \fBxx\fR
297 are hex digits interpolates to character with hex code
298 \fBxx\fR; for example
299 \fB%00\fR
300 interpolates to
301 \fB\e0\fR
302 (NUL),
303 \fB%09\fR
304 to
305 \fB\et\fR
306 (TAB) and %0a to
307 \fB\en\fR
308 (LF)\&. \-\-format cannot be combined with
309 \fB\-s\fR,
310 \fB\-o\fR,
311 \fB\-k\fR,
312 \fB\-t\fR,
313 \fB\-\-resolve\-undo\fR
314 and
315 \fB\-\-eol\fR\&.
316 .RE
317 .PP
318 \-\-
319 .RS 4
320 Do not interpret any more arguments as options\&.
321 .RE
322 .PP
323 <file>
324 .RS 4
325 Files to show\&. If no files are given all files which match the other specified criteria are shown\&.
326 .RE
327 .SH "OUTPUT"
328 .sp
329 \fIgit ls\-files\fR just outputs the filenames unless \fB\-\-stage\fR is specified in which case it outputs:
330 .sp
331 .if n \{\
332 .RS 4
333 .\}
334 .nf
335 [<tag> ]<mode> <object> <stage> <file>
336 .fi
337 .if n \{\
338 .RE
339 .\}
340 .sp
341 \fIgit ls\-files \-\-eol\fR will show i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
342 .sp
343 \fIgit ls\-files \-\-unmerged\fR and \fIgit ls\-files \-\-stage\fR can be used to examine detailed information on unmerged paths\&.
344 .sp
345 For an unmerged path, instead of recording a single mode/SHA\-1 pair, the index records up to three such pairs; one from tree O in stage 1, A in stage 2, and B in stage 3\&. This information can be used by the user (or the porcelain) to see what should eventually be recorded at the path\&. (see \fBgit-read-tree\fR(1) for more information on state)
346 .sp
347 Without the \fB\-z\fR option, pathnames with "unusual" characters are quoted as explained for the configuration variable \fBcore\&.quotePath\fR (see \fBgit-config\fR(1))\&. Using \fB\-z\fR the filename is output verbatim and the line is terminated by a NUL byte\&.
348 .sp
349 It is possible to print in a custom format by using the \fB\-\-format\fR option, which is able to interpolate different fields using a \fB%(fieldname)\fR notation\&. For example, if you only care about the "objectname" and "path" fields, you can execute with a specific "\-\-format" like
350 .sp
351 .if n \{\
352 .RS 4
353 .\}
354 .nf
355 git ls\-files \-\-format=\*(Aq%(objectname) %(path)\*(Aq
356 .fi
357 .if n \{\
358 .RE
359 .\}
360 .SH "FIELD NAMES"
361 .sp
362 The way each path is shown can be customized by using the \fB\-\-format=<format>\fR option, where the %(fieldname) in the <format> string for various aspects of the index entry are interpolated\&. The following "fieldname" are understood:
363 .PP
364 objectmode
365 .RS 4
366 The mode of the file which is recorded in the index\&.
367 .RE
368 .PP
369 objecttype
370 .RS 4
371 The object type of the file which is recorded in the index\&.
372 .RE
373 .PP
374 objectname
375 .RS 4
376 The name of the file which is recorded in the index\&.
377 .RE
378 .PP
379 objectsize[:padded]
380 .RS 4
381 The object size of the file which is recorded in the index ("\-" if the object is a
382 \fBcommit\fR
383 or
384 \fBtree\fR)\&. It also supports a padded format of size with "%(objectsize:padded)"\&.
385 .RE
386 .PP
387 stage
388 .RS 4
389 The stage of the file which is recorded in the index\&.
390 .RE
391 .PP
392 eolinfo:index, eolinfo:worktree
393 .RS 4
394 The <eolinfo> (see the description of the
395 \fB\-\-eol\fR
396 option) of the contents in the index or in the worktree for the path\&.
397 .RE
398 .PP
399 eolattr
400 .RS 4
401 The <eolattr> (see the description of the
402 \fB\-\-eol\fR
403 option) that applies to the path\&.
404 .RE
405 .PP
406 path
407 .RS 4
408 The pathname of the file which is recorded in the index\&.
409 .RE
410 .SH "EXCLUDE PATTERNS"
411 .sp
412 \fIgit ls\-files\fR can use a list of "exclude patterns" when traversing the directory tree and finding files to show when the flags \-\-others or \-\-ignored are specified\&. \fBgitignore\fR(5) specifies the format of exclude patterns\&.
413 .sp
414 Generally, you should just use \-\-exclude\-standard, but for historical reasons the exclude patterns can be specified from the following places, in order:
415 .sp
416 .RS 4
417 .ie n \{\
418 \h'-04' 1.\h'+01'\c
419 .\}
420 .el \{\
421 .sp -1
422 .IP " 1." 4.2
423 .\}
424 The command\-line flag \-\-exclude=<pattern> specifies a single pattern\&. Patterns are ordered in the same order they appear in the command line\&.
425 .RE
426 .sp
427 .RS 4
428 .ie n \{\
429 \h'-04' 2.\h'+01'\c
430 .\}
431 .el \{\
432 .sp -1
433 .IP " 2." 4.2
434 .\}
435 The command\-line flag \-\-exclude\-from=<file> specifies a file containing a list of patterns\&. Patterns are ordered in the same order they appear in the file\&.
436 .RE
437 .sp
438 .RS 4
439 .ie n \{\
440 \h'-04' 3.\h'+01'\c
441 .\}
442 .el \{\
443 .sp -1
444 .IP " 3." 4.2
445 .\}
446 The command\-line flag \-\-exclude\-per\-directory=<name> specifies a name of the file in each directory
447 \fIgit ls\-files\fR
448 examines, normally
449 \fB\&.gitignore\fR\&. Files in deeper directories take precedence\&. Patterns are ordered in the same order they appear in the files\&.
450 .RE
451 .sp
452 A pattern specified on the command line with \-\-exclude or read from the file specified with \-\-exclude\-from is relative to the top of the directory tree\&. A pattern read from a file specified by \-\-exclude\-per\-directory is relative to the directory that the pattern file appears in\&.
453 .SH "SEE ALSO"
454 .sp
455 \fBgit-read-tree\fR(1), \fBgitignore\fR(5)
456 .SH "GIT"
457 .sp
458 Part of the \fBgit\fR(1) suite