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