| blob | 2858627727fc40b7b7da0cee6248d01a1bd8e15c |
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: 01/17/2023
6 .\" Manual: Git Manual
7 .\" Source: Git 2.39.1.231.ga7caae2729
8 .\" Language: English
9 .\"
10 .TH "GIT\-LS\-FILES" "1" "01/17/2023" "Git 2\&.39\&.1\&.231\&.ga7caae" "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 [\-\-directory [\-\-no\-empty\-directory]] [\-\-eol]
39 [\-\-deduplicate]
40 [\-x <pattern>|\-\-exclude=<pattern>]
41 [\-X <file>|\-\-exclude\-from=<file>]
42 [\-\-exclude\-per\-directory=<file>]
43 [\-\-exclude\-standard]
44 [\-\-error\-unmatch] [\-\-with\-tree=<tree\-ish>]
45 [\-\-full\-name] [\-\-recurse\-submodules]
46 [\-\-abbrev[=<n>]] [\-\-format=<format>] [\-\-] [<file>\&...]
47 .fi
48 .sp
49 .SH "DESCRIPTION"
50 .sp
51 This merges the file listing in the index with the actual working directory list, and shows different combinations of the two\&.
52 .sp
53 One or more of the options below may be used to determine the files shown:
54 .SH "OPTIONS"
55 .PP
56 \-c, \-\-cached
57 .RS 4
58 Show cached files in the output (default)
59 .RE
60 .PP
61 \-d, \-\-deleted
62 .RS 4
63 Show deleted files in the output
64 .RE
65 .PP
66 \-m, \-\-modified
67 .RS 4
68 Show modified files in the output
69 .RE
70 .PP
71 \-o, \-\-others
72 .RS 4
73 Show other (i\&.e\&. untracked) files in the output
74 .RE
75 .PP
76 \-i, \-\-ignored
77 .RS 4
78 Show only ignored files in the output\&. When showing files in the index, print only those matched by an exclude pattern\&. When showing "other" files, show only those matched by an exclude pattern\&. Standard ignore rules are not automatically activated, therefore at least one of the
79 \fB\-\-exclude*\fR
80 options is required\&.
81 .RE
82 .PP
83 \-s, \-\-stage
84 .RS 4
85 Show staged contents\(aq mode bits, object name and stage number in the output\&.
86 .RE
87 .PP
88 \-\-directory
89 .RS 4
90 If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents\&.
91 .RE
92 .PP
93 \-\-no\-empty\-directory
94 .RS 4
95 Do not list empty directories\&. Has no effect without \-\-directory\&.
96 .RE
97 .PP
98 \-u, \-\-unmerged
99 .RS 4
100 Show unmerged files in the output (forces \-\-stage)
101 .RE
102 .PP
103 \-k, \-\-killed
104 .RS 4
105 Show files on the filesystem that need to be removed due to file/directory conflicts for checkout\-index to succeed\&.
106 .RE
107 .PP
108 \-z
109 .RS 4
110 \e0 line termination on output and do not quote filenames\&. See OUTPUT below for more information\&.
111 .RE
112 .PP
113 \-\-deduplicate
114 .RS 4
115 When only filenames are shown, suppress duplicates that may come from having multiple stages during a merge, or giving
116 \fB\-\-deleted\fR
117 and
118 \fB\-\-modified\fR
119 option at the same time\&. When any of the
120 \fB\-t\fR,
121 \fB\-\-unmerged\fR, or
122 \fB\-\-stage\fR
123 option is in use, this option has no effect\&.
124 .RE
125 .PP
126 \-x <pattern>, \-\-exclude=<pattern>
127 .RS 4
128 Skip untracked files matching pattern\&. Note that pattern is a shell wildcard pattern\&. See EXCLUDE PATTERNS below for more information\&.
129 .RE
130 .PP
131 \-X <file>, \-\-exclude\-from=<file>
132 .RS 4
133 Read exclude patterns from <file>; 1 per line\&.
134 .RE
135 .PP
136 \-\-exclude\-per\-directory=<file>
137 .RS 4
138 Read additional exclude patterns that apply only to the directory and its subdirectories in <file>\&.
139 .RE
140 .PP
141 \-\-exclude\-standard
142 .RS 4
143 Add the standard Git exclusions: \&.git/info/exclude, \&.gitignore in each directory, and the user\(cqs global exclusion file\&.
144 .RE
145 .PP
146 \-\-error\-unmatch
147 .RS 4
148 If any <file> does not appear in the index, treat this as an error (return 1)\&.
149 .RE
150 .PP
151 \-\-with\-tree=<tree\-ish>
152 .RS 4
153 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
154 \fB\-s\fR
155 or
156 \fB\-u\fR
157 options does not make any sense\&.
158 .RE
159 .PP
160 \-t
161 .RS 4
162 This feature is semi\-deprecated\&. For scripting purpose,
163 \fBgit-status\fR(1)
164 \fB\-\-porcelain\fR
165 and
166 \fBgit-diff-files\fR(1)
167 \fB\-\-name\-status\fR
168 are almost always superior alternatives, and users should look at
169 \fBgit-status\fR(1)
170 \fB\-\-short\fR
171 or
172 \fBgit-diff\fR(1)
173 \fB\-\-name\-status\fR
174 for more user\-friendly alternatives\&.
175 .sp
176 This option identifies the file status with the following tags (followed by a space) at the start of each line:
177 .PP
178 H
179 .RS 4
180 cached
181 .RE
182 .PP
183 S
184 .RS 4
185 skip\-worktree
186 .RE
187 .PP
188 M
189 .RS 4
190 unmerged
191 .RE
192 .PP
193 R
194 .RS 4
195 removed/deleted
196 .RE
197 .PP
198 C
199 .RS 4
200 modified/changed
201 .RE
202 .PP
203 K
204 .RS 4
205 to be killed
206 .RE
207 .PP
208 ?
209 .RS 4
210 other
211 .RE
212 .RE
213 .PP
214 \-v
215 .RS 4
216 Similar to
217 \fB\-t\fR, but use lowercase letters for files that are marked as
218 \fIassume unchanged\fR
219 (see
220 \fBgit-update-index\fR(1))\&.
221 .RE
222 .PP
223 \-f
224 .RS 4
225 Similar to
226 \fB\-t\fR, but use lowercase letters for files that are marked as
227 \fIfsmonitor valid\fR
228 (see
229 \fBgit-update-index\fR(1))\&.
230 .RE
231 .PP
232 \-\-full\-name
233 .RS 4
234 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\&.
235 .RE
236 .PP
237 \-\-recurse\-submodules
238 .RS 4
239 Recursively calls ls\-files on each active submodule in the repository\&. Currently there is only support for the \-\-cached and \-\-stage modes\&.
240 .RE
241 .PP
242 \-\-abbrev[=<n>]
243 .RS 4
244 Instead of showing the full 40\-byte hexadecimal object lines, show the shortest prefix that is at least
245 \fI<n>\fR
246 hexdigits long that uniquely refers the object\&. Non default number of digits can be specified with \-\-abbrev=<n>\&.
247 .RE
248 .PP
249 \-\-debug
250 .RS 4
251 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\&.
252 .RE
253 .PP
254 \-\-eol
255 .RS 4
256 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 ""\&.
257 .sp
258 "" means the file is not a regular file, it is not in the index or not accessible in the working tree\&.
259 .sp
260 <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\&.
261 .sp
262 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>")\&.
263 .RE
264 .PP
265 \-\-sparse
266 .RS 4
267 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"\&.
268 .RE
269 .PP
270 \-\-format=<format>
271 .RS 4
272 A string that interpolates
273 \fB%(fieldname)\fR
274 from the result being shown\&. It also interpolates
275 \fB%%\fR
276 to
277 \fB%\fR, and
278 \fB%xx\fR
279 where
280 \fBxx\fR
281 are hex digits interpolates to character with hex code
282 \fBxx\fR; for example
283 \fB%00\fR
284 interpolates to
285 \fB\e0\fR
286 (NUL),
287 \fB%09\fR
288 to
289 \fB\et\fR
290 (TAB) and %0a to
291 \fB\en\fR
292 (LF)\&. \-\-format cannot be combined with
293 \fB\-s\fR,
294 \fB\-o\fR,
295 \fB\-k\fR,
296 \fB\-t\fR,
297 \fB\-\-resolve\-undo\fR
298 and
299 \fB\-\-eol\fR\&.
300 .RE
301 .PP
302 \-\-
303 .RS 4
304 Do not interpret any more arguments as options\&.
305 .RE
306 .PP
307 <file>
308 .RS 4
309 Files to show\&. If no files are given all files which match the other specified criteria are shown\&.
310 .RE
311 .SH "OUTPUT"
312 .sp
313 \fIgit ls\-files\fR just outputs the filenames unless \fB\-\-stage\fR is specified in which case it outputs:
314 .sp
315 .if n \{\
316 .RS 4
317 .\}
318 .nf
319 [<tag> ]<mode> <object> <stage> <file>
320 .fi
321 .if n \{\
322 .RE
323 .\}
324 .sp
325 \fIgit ls\-files \-\-eol\fR will show i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
326 .sp
327 \fIgit ls\-files \-\-unmerged\fR and \fIgit ls\-files \-\-stage\fR can be used to examine detailed information on unmerged paths\&.
328 .sp
329 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)
330 .sp
331 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\&.
332 .sp
333 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
334 .sp
335 .if n \{\
336 .RS 4
337 .\}
338 .nf
339 git ls\-files \-\-format=\(aq%(objectname) %(path)\(aq
340 .fi
341 .if n \{\
342 .RE
343 .\}
344 .SH "FIELD NAMES"
345 .sp
346 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:
347 .PP
348 objectmode
349 .RS 4
350 The mode of the file which is recorded in the index\&.
351 .RE
352 .PP
353 objectname
354 .RS 4
355 The name of the file which is recorded in the index\&.
356 .RE
357 .PP
358 stage
359 .RS 4
360 The stage of the file which is recorded in the index\&.
361 .RE
362 .PP
363 eolinfo:index, eolinfo:worktree
364 .RS 4
365 The <eolinfo> (see the description of the
366 \fB\-\-eol\fR
367 option) of the contents in the index or in the worktree for the path\&.
368 .RE
369 .PP
370 eolattr
371 .RS 4
372 The <eolattr> (see the description of the
373 \fB\-\-eol\fR
374 option) that applies to the path\&.
375 .RE
376 .PP
377 path
378 .RS 4
379 The pathname of the file which is recorded in the index\&.
380 .RE
381 .SH "EXCLUDE PATTERNS"
382 .sp
383 \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\&.
384 .sp
385 These exclude patterns come from these places, in order:
386 .sp
387 .RS 4
388 .ie n \{\
389 \h'-04' 1.\h'+01'\c
390 .\}
391 .el \{\
392 .sp -1
393 .IP " 1." 4.2
394 .\}
395 The command\-line flag \-\-exclude=<pattern> specifies a single pattern\&. Patterns are ordered in the same order they appear in the command line\&.
396 .RE
397 .sp
398 .RS 4
399 .ie n \{\
400 \h'-04' 2.\h'+01'\c
401 .\}
402 .el \{\
403 .sp -1
404 .IP " 2." 4.2
405 .\}
406 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\&.
407 .RE
408 .sp
409 .RS 4
410 .ie n \{\
411 \h'-04' 3.\h'+01'\c
412 .\}
413 .el \{\
414 .sp -1
415 .IP " 3." 4.2
416 .\}
417 The command\-line flag \-\-exclude\-per\-directory=<name> specifies a name of the file in each directory
418 \fIgit ls\-files\fR
419 examines, normally
420 \fB\&.gitignore\fR\&. Files in deeper directories take precedence\&. Patterns are ordered in the same order they appear in the files\&.
421 .RE
422 .sp
423 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\&.
424 .SH "SEE ALSO"
425 .sp
426 \fBgit-read-tree\fR(1), \fBgitignore\fR(5)
427 .SH "GIT"
428 .sp
429 Part of the \fBgit\fR(1) suite