]>
Commit | Line | Data |
---|---|---|
2cf565c5 DG |
1 | git-ls-files(1) |
2 | =============== | |
2cf565c5 DG |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-ls-files - Show information about files in the index and the working tree |
2cf565c5 DG |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
f9666adf | 11 | [verse] |
780494b1 | 12 | 'git ls-files' [-z] [-t] [-v] [-f] |
a6c6f6d2 VB |
13 | [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored] |
14 | [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified] | |
2a34b318 | 15 | [--resolve-undo] |
89557d68 | 16 | [--directory [--no-empty-directory]] [--eol] |
93a7d983 | 17 | [--deduplicate] |
2cf565c5 DG |
18 | [-x <pattern>|--exclude=<pattern>] |
19 | [-X <file>|--exclude-from=<file>] | |
ad0cae4c | 20 | [--exclude-per-directory=<file>] |
8e7b07c8 | 21 | [--exclude-standard] |
a7a0f3d3 | 22 | [--error-unmatch] [--with-tree=<tree-ish>] |
e77aa336 | 23 | [--full-name] [--recurse-submodules] |
ce74de93 | 24 | [--abbrev[=<n>]] [--format=<format>] [--] [<file>...] |
2cf565c5 DG |
25 | |
26 | DESCRIPTION | |
27 | ----------- | |
cf6cac20 | 28 | This command merges the file listing in the index with the actual working |
b356d236 | 29 | directory list, and shows different combinations of the two. |
2cf565c5 | 30 | |
cf6cac20 | 31 | Several flags can be used to determine which files are |
2b02d2df | 32 | shown, and each file may be printed multiple times if there are |
cf6cac20 | 33 | multiple entries in the index or if multiple statuses are applicable for |
2b02d2df | 34 | the relevant file selection options. |
2cf565c5 DG |
35 | |
36 | OPTIONS | |
37 | ------- | |
3240240f SB |
38 | -c:: |
39 | --cached:: | |
2b02d2df EN |
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.) | |
2cf565c5 | 43 | |
3240240f SB |
44 | -d:: |
45 | --deleted:: | |
2b02d2df | 46 | Show files with an unstaged deletion |
2cf565c5 | 47 | |
3240240f SB |
48 | -m:: |
49 | --modified:: | |
2b02d2df EN |
50 | Show files with an unstaged modification (note that an unstaged |
51 | deletion also counts as an unstaged modification) | |
b0391890 | 52 | |
3240240f SB |
53 | -o:: |
54 | --others:: | |
4d590f06 | 55 | Show other (i.e. untracked) files in the output |
2cf565c5 | 56 | |
3240240f SB |
57 | -i:: |
58 | --ignored:: | |
2b02d2df EN |
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 | |
f4e1851a | 65 | activated; therefore, at least one of the `--exclude*` options |
2b02d2df | 66 | is required. |
2cf565c5 | 67 | |
3240240f SB |
68 | -s:: |
69 | --stage:: | |
be6ed145 | 70 | Show staged contents' mode bits, object name and stage number in the output. |
2cf565c5 | 71 | |
a3259570 PB |
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. | |
2b02d2df | 75 | Has no effect without -o/--others. |
a3259570 | 76 | |
b0a3de42 PB |
77 | --no-empty-directory:: |
78 | Do not list empty directories. Has no effect without --directory. | |
79 | ||
3240240f SB |
80 | -u:: |
81 | --unmerged:: | |
2b02d2df EN |
82 | Show information about unmerged files in the output, but do |
83 | not show any other tracked files (forces --stage, overrides | |
84 | --cached). | |
2cf565c5 | 85 | |
3240240f SB |
86 | -k:: |
87 | --killed:: | |
2b02d2df EN |
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. | |
6ca45943 | 91 | |
2a34b318 EN |
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 | ||
2cf565c5 | 99 | -z:: |
860cd699 AH |
100 | \0 line termination on output and do not quote filenames. |
101 | See OUTPUT below for more information. | |
2cf565c5 | 102 | |
93a7d983 ZH |
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 | ||
3240240f SB |
110 | -x <pattern>:: |
111 | --exclude=<pattern>:: | |
4c608520 | 112 | Skip untracked files matching pattern. |
75609a0d JS |
113 | Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS |
114 | below for more information. | |
2cf565c5 | 115 | |
3240240f SB |
116 | -X <file>:: |
117 | --exclude-from=<file>:: | |
4c608520 | 118 | Read exclude patterns from <file>; 1 per line. |
30b0535f JH |
119 | |
120 | --exclude-per-directory=<file>:: | |
4c608520 | 121 | Read additional exclude patterns that apply only to the |
0009542c JH |
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. | |
2cf565c5 | 126 | |
8e7b07c8 | 127 | --exclude-standard:: |
2de9b711 | 128 | Add the standard Git exclusions: .git/info/exclude, .gitignore |
8e7b07c8 JK |
129 | in each directory, and the user's global exclusion file. |
130 | ||
c8af25ca CW |
131 | --error-unmatch:: |
132 | If any <file> does not appear in the index, treat this as an | |
133 | error (return 1). | |
134 | ||
a7a0f3d3 JH |
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 | ||
2cf565c5 | 142 | -t:: |
4173b806 EN |
143 | Show status tags together with filenames. Note that for |
144 | scripting purposes, linkgit:git-status[1] `--porcelain` and | |
5bc0e247 | 145 | linkgit:git-diff-files[1] `--name-status` are almost always |
f4e1851a | 146 | superior alternatives; users should look at |
5bc0e247 MM |
147 | linkgit:git-status[1] `--short` or linkgit:git-diff[1] |
148 | `--name-status` for more user-friendly alternatives. | |
149 | + | |
da9ca955 | 150 | -- |
4173b806 EN |
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: | |
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 | |
da9ca955 | 164 | -- |
2cf565c5 | 165 | |
f9666adf JH |
166 | -v:: |
167 | Similar to `-t`, but use lowercase letters for files | |
56c3eb17 | 168 | that are marked as 'assume unchanged' (see |
5162e697 | 169 | linkgit:git-update-index[1]). |
f9666adf | 170 | |
780494b1 BP |
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 | ||
9a84074d JH |
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 | ||
e77aa336 | 182 | --recurse-submodules:: |
acbfae32 | 183 | Recursively calls ls-files on each active submodule in the repository. |
290eada0 | 184 | Currently there is only support for the --cached and --stage modes. |
e77aa336 | 185 | |
ad0cae4c EW |
186 | --abbrev[=<n>]:: |
187 | Instead of showing the full 40-byte hexadecimal object | |
cda34e0d JH |
188 | lines, show the shortest prefix that is at least '<n>' |
189 | hexdigits long that uniquely refers the object. | |
ad0cae4c EW |
190 | Non default number of digits can be specified with --abbrev=<n>. |
191 | ||
84974217 TR |
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 | ||
a7630bd4 TB |
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 | |
d285ab0a | 205 | not accessible in the working tree. |
a7630bd4 TB |
206 | + |
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". | |
41a616da | 209 | Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported. |
a7630bd4 TB |
210 | + |
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>"). | |
214 | ||
78087097 DS |
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 | ||
ce74de93 ZH |
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`. | |
e994004f | 227 | \--:: |
500b97e4 FK |
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 | ||
76a8788c | 234 | OUTPUT |
2cf565c5 | 235 | ------ |
bcf9626a | 236 | 'git ls-files' just outputs the filenames unless `--stage` is specified in |
2cf565c5 DG |
237 | which case it outputs: |
238 | ||
239 | [<tag> ]<mode> <object> <stage> <file> | |
240 | ||
a7630bd4 TB |
241 | 'git ls-files --eol' will show |
242 | i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file> | |
243 | ||
0b444cdb | 244 | 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine |
2cf565c5 DG |
245 | detailed information on unmerged paths. |
246 | ||
d5fa1f1a | 247 | For an unmerged path, instead of recording a single mode/SHA-1 pair, |
5adf317b | 248 | the index records up to three such pairs; one from tree O in stage |
2cf565c5 | 249 | 1, A in stage 2, and B in stage 3. This information can be used by |
2c6e4771 | 250 | the user (or the porcelain) to see what should eventually be recorded at the |
483bc4f0 | 251 | path. (see linkgit:git-read-tree[1] for more information on state) |
2cf565c5 | 252 | |
860cd699 AH |
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. | |
d88156e9 | 257 | |
ce74de93 ZH |
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 | |
263 | ||
264 | git ls-files --format='%(objectname) %(path)' | |
265 | ||
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: | |
272 | ||
273 | objectmode:: | |
274 | The mode of the file which is recorded in the index. | |
4d28c4f7 ZH |
275 | objecttype:: |
276 | The object type of the file which is recorded in the index. | |
ce74de93 ZH |
277 | objectname:: |
278 | The name of the file which is recorded in the index. | |
4d28c4f7 ZH |
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)". | |
ce74de93 ZH |
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. | |
30b0535f | 294 | |
76a8788c | 295 | EXCLUDE PATTERNS |
30b0535f JH |
296 | ---------------- |
297 | ||
0b444cdb | 298 | 'git ls-files' can use a list of "exclude patterns" when |
30b0535f | 299 | traversing the directory tree and finding files to show when the |
5162e697 | 300 | flags --others or --ignored are specified. linkgit:gitignore[5] |
cedb8d5d | 301 | specifies the format of exclude patterns. |
30b0535f | 302 | |
0009542c JH |
303 | These exclude patterns can be specified from the following places, |
304 | in order: | |
30b0535f | 305 | |
06ab60c0 | 306 | 1. The command-line flag --exclude=<pattern> specifies a |
cedb8d5d JT |
307 | single pattern. Patterns are ordered in the same order |
308 | they appear in the command line. | |
30b0535f | 309 | |
06ab60c0 | 310 | 2. The command-line flag --exclude-from=<file> specifies a |
cedb8d5d JT |
311 | file containing a list of patterns. Patterns are ordered |
312 | in the same order they appear in the file. | |
30b0535f | 313 | |
06ab60c0 | 314 | 3. The command-line flag --exclude-per-directory=<name> specifies |
0b444cdb | 315 | a name of the file in each directory 'git ls-files' |
cedb8d5d JT |
316 | examines, normally `.gitignore`. Files in deeper |
317 | directories take precedence. Patterns are ordered in the | |
318 | same order they appear in the files. | |
30b0535f JH |
319 | |
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. | |
325 | ||
0009542c JH |
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: | |
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 | ||
336 | via the `--exclude-from=` option. | |
337 | ||
56ae8df5 | 338 | SEE ALSO |
c1bdacf9 | 339 | -------- |
5162e697 | 340 | linkgit:git-read-tree[1], linkgit:gitignore[5] |
2cf565c5 | 341 | |
2cf565c5 DG |
342 | GIT |
343 | --- | |
9e1f0a85 | 344 | Part of the linkgit:git[1] suite |