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