git-ls-files(1)

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]
11                       (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
12                       (-[c|d|o|i|s|u|k|m])*
13                       [-x <pattern>|--exclude=<pattern>]
14                       [-X <file>|--exclude-from=<file>]
15                       [--exclude-per-directory=<file>]
16                       [--exclude-standard]
17                       [--error-unmatch] [--with-tree=<tree-ish>]
18                       [--full-name] [--abbrev] [--] [<file>...]
19
20

DESCRIPTION

22       This merges the file listing in the directory cache index with the
23       actual working directory list, and shows different combinations of the
24       two.
25
26       One or more of the options below may be used to determine the files
27       shown:
28

OPTIONS

30       -c, --cached
31           Show cached files in the output (default)
32
33       -d, --deleted
34           Show deleted files in the output
35
36       -m, --modified
37           Show modified files in the output
38
39       -o, --others
40           Show other (i.e. untracked) files in the output
41
42       -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
47       -s, --stage
48           Show staged contents' object name, mode bits and stage number in
49           the output.
50
51       --directory
52           If a whole directory is classified as "other", show just its name
53           (with a trailing slash) and not its whole contents.
54
55       --no-empty-directory
56           Do not list empty directories. Has no effect without --directory.
57
58       -u, --unmerged
59           Show unmerged files in the output (forces --stage)
60
61       -k, --killed
62           Show files on the filesystem that need to be removed due to
63           file/directory conflicts for checkout-index to succeed.
64
65       -z
66           \0 line termination on output.
67
68       -x <pattern>, --exclude=<pattern>
69           Skip untracked files matching pattern. Note that pattern is a shell
70           wildcard pattern. See EXCLUDE PATTERNS below for more information.
71
72       -X <file>, --exclude-from=<file>
73           Read exclude patterns from <file>; 1 per line.
74
75       --exclude-per-directory=<file>
76           Read additional exclude patterns that apply only to the directory
77           and its subdirectories in <file>.
78
79       --exclude-standard
80           Add the standard Git exclusions: .git/info/exclude, .gitignore in
81           each directory, and the user’s global exclusion file.
82
83       --error-unmatch
84           If any <file> does not appear in the index, treat this as an error
85           (return 1).
86
87       --with-tree=<tree-ish>
88           When using --error-unmatch to expand the user supplied <file> (i.e.
89           path pattern) arguments to paths, pretend that paths which were
90           removed in the index since the named <tree-ish> are still present.
91           Using this option with -s or -u options does not make any sense.
92
93       -t
94           This feature is semi-deprecated. For scripting purpose, git-
95           status(1)--porcelain and git-diff-files(1)--name-status are almost
96           always superior alternatives, and users should look at git-
97           status(1)--short or git-diff(1)--name-status for more user-friendly
98           alternatives.
99
100           This option identifies the file status with the following tags
101           (followed by a space) at the start of each line:
102
103       H
104           cached
105
106       S
107           skip-worktree
108
109       M
110           unmerged
111
112       R
113           removed/deleted
114
115       C
116           modified/changed
117
118       K
119           to be killed
120
121       ?
122           other
123
124       -v
125           Similar to -t, but use lowercase letters for files that are marked
126           as assume unchanged (see git-update-index(1)).
127
128       --full-name
129           When run from a subdirectory, the command usually outputs paths
130           relative to the current directory. This option forces paths to be
131           output relative to the project top directory.
132
133       --abbrev[=<n>]
134           Instead of showing the full 40-byte hexadecimal object lines, show
135           only a partial prefix. Non default number of digits can be
136           specified with --abbrev=<n>.
137
138       --debug
139           After each line that describes a file, add more data about its
140           cache entry. This is intended to show as much information as
141           possible for manual inspection; the exact format may change at any
142           time.
143
144       --
145           Do not interpret any more arguments as options.
146
147       <file>
148           Files to show. If no files are given all files which match the
149           other specified criteria are shown.
150

OUTPUT

152       git ls-files just outputs the filenames unless --stage is specified in
153       which case it outputs:
154
155           [<tag> ]<mode> <object> <stage> <file>
156
157       git ls-files --unmerged and git ls-files --stage can be used to examine
158       detailed information on unmerged paths.
159
160       For an unmerged path, instead of recording a single mode/SHA-1 pair,
161       the index records up to three such pairs; one from tree O in stage 1, A
162       in stage 2, and B in stage 3. This information can be used by the user
163       (or the porcelain) to see what should eventually be recorded at the
164       path. (see git-read-tree(1) for more information on state)
165
166       When -z option is not used, TAB, LF, and backslash characters in
167       pathnames are represented as \t, \n, and \\, respectively.
168

EXCLUDE PATTERNS

170       git ls-files can use a list of "exclude patterns" when traversing the
171       directory tree and finding files to show when the flags --others or
172       --ignored are specified. gitignore(5) specifies the format of exclude
173       patterns.
174
175       These exclude patterns come from these places, in order:
176
177        1. The command line flag --exclude=<pattern> specifies a single
178           pattern. Patterns are ordered in the same order they appear in the
179           command line.
180
181        2. The command line flag --exclude-from=<file> specifies a file
182           containing a list of patterns. Patterns are ordered in the same
183           order they appear in the file.
184
185        3. The command line flag --exclude-per-directory=<name> specifies a
186           name of the file in each directory git ls-files examines, normally
187           .gitignore. Files in deeper directories take precedence. Patterns
188           are ordered in the same order they appear in the files.
189
190       A pattern specified on the command line with --exclude or read from the
191       file specified with --exclude-from is relative to the top of the
192       directory tree. A pattern read from a file specified by
193       --exclude-per-directory is relative to the directory that the pattern
194       file appears in.
195

GIT

200       Part of the git(1) suite
201
202
203
204Git 1.8.3.1                       11/19/2018                   GIT-LS-FILES(1)