]>
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 | ----------- | |
b356d236 UG |
28 | This merges the file listing in the index with the actual working |
29 | directory list, and shows different combinations of the two. | |
2cf565c5 DG |
30 | |
31 | One or more of the options below may be used to determine the files | |
2b02d2df EN |
32 | shown, and each file may be printed multiple times if there are |
33 | multiple entries in the index or multiple statuses are applicable for | |
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 | |
65 | activated, therefore at least one of the `--exclude*` options | |
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 |
e750951e EN |
122 | directory and its subdirectories in <file>. Deprecated; use |
123 | --exclude-standard instead. | |
2cf565c5 | 124 | |
8e7b07c8 | 125 | --exclude-standard:: |
2de9b711 | 126 | Add the standard Git exclusions: .git/info/exclude, .gitignore |
8e7b07c8 JK |
127 | in each directory, and the user's global exclusion file. |
128 | ||
c8af25ca CW |
129 | --error-unmatch:: |
130 | If any <file> does not appear in the index, treat this as an | |
131 | error (return 1). | |
132 | ||
a7a0f3d3 JH |
133 | --with-tree=<tree-ish>:: |
134 | When using --error-unmatch to expand the user supplied | |
135 | <file> (i.e. path pattern) arguments to paths, pretend | |
136 | that paths which were removed in the index since the | |
137 | named <tree-ish> are still present. Using this option | |
138 | with `-s` or `-u` options does not make any sense. | |
139 | ||
2cf565c5 | 140 | -t:: |
4173b806 EN |
141 | Show status tags together with filenames. Note that for |
142 | scripting purposes, linkgit:git-status[1] `--porcelain` and | |
5bc0e247 MM |
143 | linkgit:git-diff-files[1] `--name-status` are almost always |
144 | superior alternatives, and users should look at | |
145 | linkgit:git-status[1] `--short` or linkgit:git-diff[1] | |
146 | `--name-status` for more user-friendly alternatives. | |
147 | + | |
da9ca955 | 148 | -- |
4173b806 EN |
149 | This option provides a reason for showing each filename, in the form |
150 | of a status tag (which is followed by a space and then the filename). | |
151 | The status tags are all single characters from the following list: | |
152 | ||
153 | H:: tracked file that is not either unmerged or skip-worktree | |
154 | S:: tracked file that is skip-worktree | |
155 | M:: tracked file that is unmerged | |
156 | R:: tracked file with unstaged removal/deletion | |
157 | C:: tracked file with unstaged modification/change | |
158 | K:: untracked paths which are part of file/directory conflicts | |
159 | which prevent checking out tracked files | |
160 | ?:: untracked file | |
161 | U:: file with resolve-undo information | |
da9ca955 | 162 | -- |
2cf565c5 | 163 | |
f9666adf JH |
164 | -v:: |
165 | Similar to `-t`, but use lowercase letters for files | |
56c3eb17 | 166 | that are marked as 'assume unchanged' (see |
5162e697 | 167 | linkgit:git-update-index[1]). |
f9666adf | 168 | |
780494b1 BP |
169 | -f:: |
170 | Similar to `-t`, but use lowercase letters for files | |
171 | that are marked as 'fsmonitor valid' (see | |
172 | linkgit:git-update-index[1]). | |
173 | ||
9a84074d JH |
174 | --full-name:: |
175 | When run from a subdirectory, the command usually | |
176 | outputs paths relative to the current directory. This | |
177 | option forces paths to be output relative to the project | |
178 | top directory. | |
179 | ||
e77aa336 | 180 | --recurse-submodules:: |
acbfae32 | 181 | Recursively calls ls-files on each active submodule in the repository. |
290eada0 | 182 | Currently there is only support for the --cached and --stage modes. |
e77aa336 | 183 | |
ad0cae4c EW |
184 | --abbrev[=<n>]:: |
185 | Instead of showing the full 40-byte hexadecimal object | |
cda34e0d JH |
186 | lines, show the shortest prefix that is at least '<n>' |
187 | hexdigits long that uniquely refers the object. | |
ad0cae4c EW |
188 | Non default number of digits can be specified with --abbrev=<n>. |
189 | ||
84974217 TR |
190 | --debug:: |
191 | After each line that describes a file, add more data about its | |
192 | cache entry. This is intended to show as much information as | |
193 | possible for manual inspection; the exact format may change at | |
194 | any time. | |
195 | ||
a7630bd4 TB |
196 | --eol:: |
197 | Show <eolinfo> and <eolattr> of files. | |
198 | <eolinfo> is the file content identification used by Git when | |
199 | the "text" attribute is "auto" (or not set and core.autocrlf is not false). | |
200 | <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "". | |
201 | + | |
202 | "" means the file is not a regular file, it is not in the index or | |
d285ab0a | 203 | not accessible in the working tree. |
a7630bd4 TB |
204 | + |
205 | <eolattr> is the attribute that is used when checking out or committing, | |
206 | it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". | |
41a616da | 207 | Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported. |
a7630bd4 TB |
208 | + |
209 | Both the <eolinfo> in the index ("i/<eolinfo>") | |
210 | and in the working tree ("w/<eolinfo>") are shown for regular files, | |
211 | followed by the ("attr/<eolattr>"). | |
212 | ||
78087097 DS |
213 | --sparse:: |
214 | If the index is sparse, show the sparse directories without expanding | |
215 | to the contained files. Sparse directories will be shown with a | |
216 | trailing slash, such as "x/" for a sparse directory "x". | |
217 | ||
ce74de93 ZH |
218 | --format=<format>:: |
219 | A string that interpolates `%(fieldname)` from the result being shown. | |
220 | It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits | |
221 | interpolates to character with hex code `xx`; for example `%00` | |
222 | interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF). | |
223 | --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo` | |
224 | and `--eol`. | |
e994004f | 225 | \--:: |
500b97e4 FK |
226 | Do not interpret any more arguments as options. |
227 | ||
228 | <file>:: | |
229 | Files to show. If no files are given all files which match the other | |
230 | specified criteria are shown. | |
231 | ||
76a8788c | 232 | OUTPUT |
2cf565c5 | 233 | ------ |
bcf9626a | 234 | 'git ls-files' just outputs the filenames unless `--stage` is specified in |
2cf565c5 DG |
235 | which case it outputs: |
236 | ||
237 | [<tag> ]<mode> <object> <stage> <file> | |
238 | ||
a7630bd4 TB |
239 | 'git ls-files --eol' will show |
240 | i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file> | |
241 | ||
0b444cdb | 242 | 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine |
2cf565c5 DG |
243 | detailed information on unmerged paths. |
244 | ||
d5fa1f1a | 245 | For an unmerged path, instead of recording a single mode/SHA-1 pair, |
5adf317b | 246 | the index records up to three such pairs; one from tree O in stage |
2cf565c5 | 247 | 1, A in stage 2, and B in stage 3. This information can be used by |
2c6e4771 | 248 | the user (or the porcelain) to see what should eventually be recorded at the |
483bc4f0 | 249 | path. (see linkgit:git-read-tree[1] for more information on state) |
2cf565c5 | 250 | |
860cd699 AH |
251 | Without the `-z` option, pathnames with "unusual" characters are |
252 | quoted as explained for the configuration variable `core.quotePath` | |
253 | (see linkgit:git-config[1]). Using `-z` the filename is output | |
254 | verbatim and the line is terminated by a NUL byte. | |
d88156e9 | 255 | |
ce74de93 ZH |
256 | It is possible to print in a custom format by using the `--format` |
257 | option, which is able to interpolate different fields using | |
258 | a `%(fieldname)` notation. For example, if you only care about the | |
259 | "objectname" and "path" fields, you can execute with a specific | |
260 | "--format" like | |
261 | ||
262 | git ls-files --format='%(objectname) %(path)' | |
263 | ||
264 | FIELD NAMES | |
265 | ----------- | |
266 | The way each path is shown can be customized by using the | |
267 | `--format=<format>` option, where the %(fieldname) in the | |
268 | <format> string for various aspects of the index entry are | |
269 | interpolated. The following "fieldname" are understood: | |
270 | ||
271 | objectmode:: | |
272 | The mode of the file which is recorded in the index. | |
273 | objectname:: | |
274 | The name of the file which is recorded in the index. | |
275 | stage:: | |
276 | The stage of the file which is recorded in the index. | |
277 | eolinfo:index:: | |
278 | eolinfo:worktree:: | |
279 | The <eolinfo> (see the description of the `--eol` option) of | |
280 | the contents in the index or in the worktree for the path. | |
281 | eolattr:: | |
282 | The <eolattr> (see the description of the `--eol` option) | |
283 | that applies to the path. | |
284 | path:: | |
285 | The pathname of the file which is recorded in the index. | |
30b0535f | 286 | |
76a8788c | 287 | EXCLUDE PATTERNS |
30b0535f JH |
288 | ---------------- |
289 | ||
0b444cdb | 290 | 'git ls-files' can use a list of "exclude patterns" when |
30b0535f | 291 | traversing the directory tree and finding files to show when the |
5162e697 | 292 | flags --others or --ignored are specified. linkgit:gitignore[5] |
cedb8d5d | 293 | specifies the format of exclude patterns. |
30b0535f | 294 | |
e750951e EN |
295 | Generally, you should just use --exclude-standard, but for historical |
296 | reasons the exclude patterns can be specified from the following | |
297 | places, in order: | |
30b0535f | 298 | |
06ab60c0 | 299 | 1. The command-line flag --exclude=<pattern> specifies a |
cedb8d5d JT |
300 | single pattern. Patterns are ordered in the same order |
301 | they appear in the command line. | |
30b0535f | 302 | |
06ab60c0 | 303 | 2. The command-line flag --exclude-from=<file> specifies a |
cedb8d5d JT |
304 | file containing a list of patterns. Patterns are ordered |
305 | in the same order they appear in the file. | |
30b0535f | 306 | |
06ab60c0 | 307 | 3. The command-line flag --exclude-per-directory=<name> specifies |
0b444cdb | 308 | a name of the file in each directory 'git ls-files' |
cedb8d5d JT |
309 | examines, normally `.gitignore`. Files in deeper |
310 | directories take precedence. Patterns are ordered in the | |
311 | same order they appear in the files. | |
30b0535f JH |
312 | |
313 | A pattern specified on the command line with --exclude or read | |
314 | from the file specified with --exclude-from is relative to the | |
315 | top of the directory tree. A pattern read from a file specified | |
316 | by --exclude-per-directory is relative to the directory that the | |
317 | pattern file appears in. | |
318 | ||
56ae8df5 | 319 | SEE ALSO |
c1bdacf9 | 320 | -------- |
5162e697 | 321 | linkgit:git-read-tree[1], linkgit:gitignore[5] |
2cf565c5 | 322 | |
2cf565c5 DG |
323 | GIT |
324 | --- | |
9e1f0a85 | 325 | Part of the linkgit:git[1] suite |