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

DESCRIPTION

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

OPTIONS

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

OUTPUT

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

EXCLUDE PATTERNS

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

SEE ALSO

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

GIT

235       Part of the git(1) suite
236
237
238
239Git 2.26.2                        2020-04-20                   GIT-LS-FILES(1)
Impressum