1GIT-LS-FILES(1) Git Manual GIT-LS-FILES(1)
2
3
4
6 git-ls-files - Show information about files in the index and the
7 working tree
8
10 git ls-files [-z] [-t] [-v] [-f]
11 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
12 (-[c|d|o|i|s|u|k|m])*
13 [--eol]
14 [-x <pattern>|--exclude=<pattern>]
15 [-X <file>|--exclude-from=<file>]
16 [--exclude-per-directory=<file>]
17 [--exclude-standard]
18 [--error-unmatch] [--with-tree=<tree-ish>]
19 [--full-name] [--recurse-submodules]
20 [--abbrev] [--] [<file>...]
21
23 This merges the file listing in the directory cache index with the
24 actual working directory list, and shows different combinations of the
25 two.
26
27 One or more of the options below may be used to determine the files
28 shown:
29
31 -c, --cached
32 Show cached files in the output (default)
33
34 -d, --deleted
35 Show deleted files in the output
36
37 -m, --modified
38 Show modified files in the output
39
40 -o, --others
41 Show other (i.e. untracked) files in the output
42
43 -i, --ignored
44 Show only ignored files in the output. When showing files in the
45 index, print only those matched by an exclude pattern. When showing
46 "other" files, show only those matched by an exclude pattern.
47 Standard ignore rules are not automatically activated, therefore at
48 least one of the --exclude* options is required.
49
50 -s, --stage
51 Show staged contents' mode bits, object name and stage number in
52 the output.
53
54 --directory
55 If a whole directory is classified as "other", show just its name
56 (with a trailing slash) and not its whole contents.
57
58 --no-empty-directory
59 Do not list empty directories. Has no effect without --directory.
60
61 -u, --unmerged
62 Show unmerged files in the output (forces --stage)
63
64 -k, --killed
65 Show files on the filesystem that need to be removed due to
66 file/directory conflicts for checkout-index to succeed.
67
68 -z
69 \0 line termination on output and do not quote filenames. See
70 OUTPUT below for more information.
71
72 -x <pattern>, --exclude=<pattern>
73 Skip untracked files matching pattern. Note that pattern is a shell
74 wildcard pattern. See EXCLUDE PATTERNS below for more information.
75
76 -X <file>, --exclude-from=<file>
77 Read exclude patterns from <file>; 1 per line.
78
79 --exclude-per-directory=<file>
80 Read additional exclude patterns that apply only to the directory
81 and its subdirectories in <file>.
82
83 --exclude-standard
84 Add the standard Git exclusions: .git/info/exclude, .gitignore in
85 each directory, and the user’s global exclusion file.
86
87 --error-unmatch
88 If any <file> does not appear in the index, treat this as an error
89 (return 1).
90
91 --with-tree=<tree-ish>
92 When using --error-unmatch to expand the user supplied <file> (i.e.
93 path pattern) arguments to paths, pretend that paths which were
94 removed in the index since the named <tree-ish> are still present.
95 Using this option with -s or -u options does not make any sense.
96
97 -t
98 This feature is semi-deprecated. For scripting purpose, git-
99 status(1) --porcelain and git-diff-files(1) --name-status are
100 almost always superior alternatives, and users should look at git-
101 status(1) --short or git-diff(1) --name-status for more
102 user-friendly alternatives.
103
104 This option identifies the file status with the following tags
105 (followed by a space) at the start of each line:
106
107 H
108 cached
109
110 S
111 skip-worktree
112
113 M
114 unmerged
115
116 R
117 removed/deleted
118
119 C
120 modified/changed
121
122 K
123 to be killed
124
125 ?
126 other
127
128 -v
129 Similar to -t, but use lowercase letters for files that are marked
130 as assume unchanged (see git-update-index(1)).
131
132 -f
133 Similar to -t, but use lowercase letters for files that are marked
134 as fsmonitor valid (see git-update-index(1)).
135
136 --full-name
137 When run from a subdirectory, the command usually outputs paths
138 relative to the current directory. This option forces paths to be
139 output relative to the project top directory.
140
141 --recurse-submodules
142 Recursively calls ls-files on each submodule in the repository.
143 Currently there is only support for the --cached mode.
144
145 --abbrev[=<n>]
146 Instead of showing the full 40-byte hexadecimal object lines, show
147 only a partial prefix. Non default number of digits can be
148 specified with --abbrev=<n>.
149
150 --debug
151 After each line that describes a file, add more data about its
152 cache entry. This is intended to show as much information as
153 possible for manual inspection; the exact format may change at any
154 time.
155
156 --eol
157 Show <eolinfo> and <eolattr> of files. <eolinfo> is the file
158 content identification used by Git when the "text" attribute is
159 "auto" (or not set and core.autocrlf is not false). <eolinfo> is
160 either "-text", "none", "lf", "crlf", "mixed" or "".
161
162 "" means the file is not a regular file, it is not in the index or
163 not accessible in the working tree.
164
165 <eolattr> is the attribute that is used when checking out or
166 committing, it is either "", "-text", "text", "text=auto", "text
167 eol=lf", "text eol=crlf". Since Git 2.10 "text=auto eol=lf" and
168 "text=auto eol=crlf" are supported.
169
170 Both the <eolinfo> in the index ("i/<eolinfo>") and in the working
171 tree ("w/<eolinfo>") are shown for regular files, followed by the
172 ("attr/<eolattr>").
173
174 --
175 Do not interpret any more arguments as options.
176
177 <file>
178 Files to show. If no files are given all files which match the
179 other specified criteria are shown.
180
182 git ls-files just outputs the filenames unless --stage is specified in
183 which case it outputs:
184
185 [<tag> ]<mode> <object> <stage> <file>
186
187 git ls-files --eol will show
188 i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
189
190 git ls-files --unmerged and git ls-files --stage can be used to examine
191 detailed information on unmerged paths.
192
193 For an unmerged path, instead of recording a single mode/SHA-1 pair,
194 the index records up to three such pairs; one from tree O in stage 1, A
195 in stage 2, and B in stage 3. This information can be used by the user
196 (or the porcelain) to see what should eventually be recorded at the
197 path. (see git-read-tree(1) for more information on state)
198
199 Without the -z option, pathnames with "unusual" characters are quoted
200 as explained for the configuration variable core.quotePath (see git-
201 config(1)). Using -z the filename is output verbatim and the line is
202 terminated by a NUL byte.
203
205 git ls-files can use a list of "exclude patterns" when traversing the
206 directory tree and finding files to show when the flags --others or
207 --ignored are specified. gitignore(5) specifies the format of exclude
208 patterns.
209
210 These exclude patterns come from these places, in order:
211
212 1. The command-line flag --exclude=<pattern> specifies a single
213 pattern. Patterns are ordered in the same order they appear in the
214 command line.
215
216 2. The command-line flag --exclude-from=<file> specifies a file
217 containing a list of patterns. Patterns are ordered in the same
218 order they appear in the file.
219
220 3. The command-line flag --exclude-per-directory=<name> specifies a
221 name of the file in each directory git ls-files examines, normally
222 .gitignore. Files in deeper directories take precedence. Patterns
223 are ordered in the same order they appear in the files.
224
225 A pattern specified on the command line with --exclude or read from the
226 file specified with --exclude-from is relative to the top of the
227 directory tree. A pattern read from a file specified by
228 --exclude-per-directory is relative to the directory that the pattern
229 file appears in.
230
232 git-read-tree(1), gitignore(5)
233
235 Part of the git(1) suite
236
237
238
239Git 2.26.2 2020-04-20 GIT-LS-FILES(1)