1GIT-LS-FILES(1) Git Manual GIT-LS-FILES(1)
2
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[=<n>]] [--] [<file>...]
21
23 This merges the file listing in the index with the actual working
24 directory list, and shows different combinations of the two.
25 One or more of the options below may be used to determine the files
27 shown:
28
30 -c, --cached
31 Show cached files in the output (default)
32 -d, --deleted
34 Show deleted files in the output
35 -m, --modified
37 Show modified files in the output
38 -o, --others
40 Show other (i.e. untracked) files in the output
41 -i, --ignored
43 Show only ignored files in the output. When showing files in the
44 index, print only those matched by an exclude pattern. When showing
45 "other" files, show only those matched by an exclude pattern.
46 Standard ignore rules are not automatically activated, therefore at
47 least one of the --exclude* options is required.
48 -s, --stage
50 Show staged contents' mode bits, object name and stage number in
51 the output.
52 --directory
54 If a whole directory is classified as "other", show just its name
55 (with a trailing slash) and not its whole contents.
56 --no-empty-directory
58 Do not list empty directories. Has no effect without --directory.
59 -u, --unmerged
61 Show unmerged files in the output (forces --stage)
62 -k, --killed
64 Show files on the filesystem that need to be removed due to
65 file/directory conflicts for checkout-index to succeed.
66 -z
68 \0 line termination on output and do not quote filenames. See
69 OUTPUT below for more information.
70 -x <pattern>, --exclude=<pattern>
72 Skip untracked files matching pattern. Note that pattern is a shell
73 wildcard pattern. See EXCLUDE PATTERNS below for more information.
74 -X <file>, --exclude-from=<file>
76 Read exclude patterns from <file>; 1 per line.
77 --exclude-per-directory=<file>
79 Read additional exclude patterns that apply only to the directory
80 and its subdirectories in <file>.
81 --exclude-standard
83 Add the standard Git exclusions: .git/info/exclude, .gitignore in
84 each directory, and the user’s global exclusion file.
85 --error-unmatch
87 If any <file> does not appear in the index, treat this as an error
88 (return 1).
89 --with-tree=<tree-ish>
91 When using --error-unmatch to expand the user supplied <file> (i.e.
92 path pattern) arguments to paths, pretend that paths which were
93 removed in the index since the named <tree-ish> are still present.
94 Using this option with -s or -u options does not make any sense.
95 -t
97 This feature is semi-deprecated. For scripting purpose, git-
98 status(1) --porcelain and git-diff-files(1) --name-status are
99 almost always superior alternatives, and users should look at git-
100 status(1) --short or git-diff(1) --name-status for more
101 user-friendly alternatives.
102 This option identifies the file status with the following tags
104 (followed by a space) at the start of each line:
105 H
107 cached
108 S
110 skip-worktree
111 M
113 unmerged
114 R
116 removed/deleted
117 C
119 modified/changed
120 K
122 to be killed
123 ?
125 other
126 -v
128 Similar to -t, but use lowercase letters for files that are marked
129 as assume unchanged (see git-update-index(1)).
130 -f
132 Similar to -t, but use lowercase letters for files that are marked
133 as fsmonitor valid (see git-update-index(1)).
134 --full-name
136 When run from a subdirectory, the command usually outputs paths
137 relative to the current directory. This option forces paths to be
138 output relative to the project top directory.
139 --recurse-submodules
141 Recursively calls ls-files on each active submodule in the
142 repository. Currently there is only support for the --cached mode.
143 --abbrev[=<n>]
145 Instead of showing the full 40-byte hexadecimal object lines, show
146 the shortest prefix that is at least <n> hexdigits long that
147 uniquely refers the object. Non default number of digits can be
148 specified with --abbrev=<n>.
149 --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 --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 "" means the file is not a regular file, it is not in the index or
163 not accessible in the working tree.
164 <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 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 --
175 Do not interpret any more arguments as options.
176 <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 [<tag> ]<mode> <object> <stage> <file>
186 git ls-files --eol will show
188 i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
189 git ls-files --unmerged and git ls-files --stage can be used to examine
191 detailed information on unmerged paths.
192 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 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 These exclude patterns come from these places, in order:
211 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 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 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 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
236Git 2.30.2 2021-03-08 GIT-LS-FILES(1)