1GIT-LS-FILES(1)                   Git Manual                   GIT-LS-FILES(1)
2
3
4

NAME

6       git-ls-files - Show information about files in the index and the
7       working tree
8

SYNOPSIS

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
22

DESCRIPTION

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
28       One or more of the options below may be used to determine the files
29       shown:
30

OPTIONS

32       -c, --cached
33           Show cached files in the output (default)
34
35       -d, --deleted
36           Show deleted files in the output
37
38       -m, --modified
39           Show modified files in the output
40
41       -o, --others
42           Show other (i.e. untracked) files in the output
43
44       -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
51       -s, --stage
52           Show staged contents' mode bits, object name and stage number in
53           the output.
54
55       --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
59       --no-empty-directory
60           Do not list empty directories. Has no effect without --directory.
61
62       -u, --unmerged
63           Show unmerged files in the output (forces --stage)
64
65       -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
69       -z
70           \0 line termination on output and do not quote filenames. See
71           OUTPUT below for more information.
72
73       -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
77       -X <file>, --exclude-from=<file>
78           Read exclude patterns from <file>; 1 per line.
79
80       --exclude-per-directory=<file>
81           Read additional exclude patterns that apply only to the directory
82           and its subdirectories in <file>.
83
84       --exclude-standard
85           Add the standard Git exclusions: .git/info/exclude, .gitignore in
86           each directory, and the user’s global exclusion file.
87
88       --error-unmatch
89           If any <file> does not appear in the index, treat this as an error
90           (return 1).
91
92       --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
98       -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
105           This option identifies the file status with the following tags
106           (followed by a space) at the start of each line:
107
108       H
109           cached
110
111       S
112           skip-worktree
113
114       M
115           unmerged
116
117       R
118           removed/deleted
119
120       C
121           modified/changed
122
123       K
124           to be killed
125
126       ?
127           other
128
129       -v
130           Similar to -t, but use lowercase letters for files that are marked
131           as assume unchanged (see git-update-index(1)).
132
133       -f
134           Similar to -t, but use lowercase letters for files that are marked
135           as fsmonitor valid (see git-update-index(1)).
136
137       --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
142       --recurse-submodules
143           Recursively calls ls-files on each submodule in the repository.
144           Currently there is only support for the --cached mode.
145
146       --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
151       --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
157       --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
163           "" means the file is not a regular file, it is not in the index or
164           not accessible in the working tree.
165
166           <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
171           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
175       --
176           Do not interpret any more arguments as options.
177
178       <file>
179           Files to show. If no files are given all files which match the
180           other specified criteria are shown.
181

OUTPUT

183       git ls-files just outputs the filenames unless --stage is specified in
184       which case it outputs:
185
186           [<tag> ]<mode> <object> <stage> <file>
187
188       git ls-files --eol will show
189       i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
190
191       git ls-files --unmerged and git ls-files --stage can be used to examine
192       detailed information on unmerged paths.
193
194       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
200       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

EXCLUDE PATTERNS

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
211       These exclude patterns come from these places, in order:
212
213        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
217        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
221        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
226       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

SEE ALSO

233       git-read-tree(1), gitignore(5)
234

GIT

236       Part of the git(1) suite
237
238
239
240Git 2.21.0                        02/24/2019                   GIT-LS-FILES(1)
Impressum