Merge branch 'fix'
[git/git.git] / Documentation / git-ls-files.txt
1 git-ls-files(1)
2 ===============
3
4 NAME
5 ----
6 git-ls-files - Information about files in the index/working directory
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git-ls-files' [-z] [-t] [-v]
13 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
14 (-[c|d|o|i|s|u|k|m])\*
15 [-x <pattern>|--exclude=<pattern>]
16 [-X <file>|--exclude-from=<file>]
17 [--exclude-per-directory=<file>]
18 [--error-unmatch]
19 [--full-name] [--abbrev] [--] [<file>]\*
20
21 DESCRIPTION
22 -----------
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
30 OPTIONS
31 -------
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 files in the output
43
44 -i|--ignored::
45 Show ignored files in the output
46 Note the this also reverses any exclude list present.
47
48 -s|--stage::
49 Show stage files in the output
50
51 --directory::
52 If a whole directory is classified as "other", show just its
53 name (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
63 to file/directory conflicts for checkout-index to
64 succeed.
65
66 -z::
67 \0 line termination on output.
68
69 -x|--exclude=<pattern>::
70 Skips files matching pattern.
71 Note that pattern is a shell wildcard pattern.
72
73 -X|--exclude-from=<file>::
74 exclude patterns are read from <file>; 1 per line.
75
76 --exclude-per-directory=<file>::
77 read additional exclude patterns that apply only to the
78 directory and its subdirectories in <file>.
79
80 --error-unmatch::
81 If any <file> does not appear in the index, treat this as an
82 error (return 1).
83
84 -t::
85 Identify the file status with the following tags (followed by
86 a space) at the start of each line:
87 H:: cached
88 M:: unmerged
89 R:: removed/deleted
90 C:: modified/changed
91 K:: to be killed
92 ?:: other
93
94 -v::
95 Similar to `-t`, but use lowercase letters for files
96 that are marked as 'always matching index'.
97
98 --full-name::
99 When run from a subdirectory, the command usually
100 outputs paths relative to the current directory. This
101 option forces paths to be output relative to the project
102 top directory.
103
104 --abbrev[=<n>]::
105 Instead of showing the full 40-byte hexadecimal object
106 lines, show only handful hexdigits prefix.
107 Non default number of digits can be specified with --abbrev=<n>.
108
109 \--::
110 Do not interpret any more arguments as options.
111
112 <file>::
113 Files to show. If no files are given all files which match the other
114 specified criteria are shown.
115
116 Output
117 ------
118 show files just outputs the filename unless '--stage' is specified in
119 which case it outputs:
120
121 [<tag> ]<mode> <object> <stage> <file>
122
123 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
124 detailed information on unmerged paths.
125
126 For an unmerged path, instead of recording a single mode/SHA1 pair,
127 the dircache records up to three such pairs; one from tree O in stage
128 1, A in stage 2, and B in stage 3. This information can be used by
129 the user (or the porcelain) to see what should eventually be recorded at the
130 path. (see git-read-tree for more information on state)
131
132 When `-z` option is not used, TAB, LF, and backslash characters
133 in pathnames are represented as `\t`, `\n`, and `\\`,
134 respectively.
135
136
137 Exclude Patterns
138 ----------------
139
140 'git-ls-files' can use a list of "exclude patterns" when
141 traversing the directory tree and finding files to show when the
142 flags --others or --ignored are specified.
143
144 These exclude patterns come from these places:
145
146 1. command line flag --exclude=<pattern> specifies a single
147 pattern.
148
149 2. command line flag --exclude-from=<file> specifies a list of
150 patterns stored in a file.
151
152 3. command line flag --exclude-per-directory=<name> specifies
153 a name of the file in each directory 'git-ls-files'
154 examines, and if exists, its contents are used as an
155 additional list of patterns.
156
157 An exclude pattern file used by (2) and (3) contains one pattern
158 per line. A line that starts with a '#' can be used as comment
159 for readability.
160
161 There are three lists of patterns that are in effect at a given
162 time. They are built and ordered in the following way:
163
164 * --exclude=<pattern> from the command line; patterns are
165 ordered in the same order as they appear on the command line.
166
167 * lines read from --exclude-from=<file>; patterns are ordered
168 in the same order as they appear in the file.
169
170 * When --exclude-per-directory=<name> is specified, upon
171 entering a directory that has such a file, its contents are
172 appended at the end of the current "list of patterns". They
173 are popped off when leaving the directory.
174
175 Each pattern in the pattern list specifies "a match pattern" and
176 optionally the fate; either a file that matches the pattern is
177 considered excluded or included. A filename is matched against
178 the patterns in the three lists; the --exclude-from list is
179 checked first, then the --exclude-per-directory list, and then
180 finally the --exclude list. The last match determines its fate.
181 If there is no match in the three lists, the fate is "included".
182
183 A pattern specified on the command line with --exclude or read
184 from the file specified with --exclude-from is relative to the
185 top of the directory tree. A pattern read from a file specified
186 by --exclude-per-directory is relative to the directory that the
187 pattern file appears in.
188
189 An exclude pattern is of the following format:
190
191 - an optional prefix '!' which means that the fate this pattern
192 specifies is "include", not the usual "exclude"; the
193 remainder of the pattern string is interpreted according to
194 the following rules.
195
196 - if it does not contain a slash '/', it is a shell glob
197 pattern and used to match against the filename without
198 leading directories (i.e. the same way as the current
199 implementation).
200
201 - otherwise, it is a shell glob pattern, suitable for
202 consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a
203 slash in the pattern must match a slash in the pathname.
204 "Documentation/\*.html" matches "Documentation/git.html" but
205 not "ppc/ppc.html". As a natural exception, "/*.c" matches
206 "cat-file.c" but not "mozilla-sha1/sha1.c".
207
208 An example:
209
210 --------------------------------------------------------------
211 $ cat .git/ignore
212 # ignore objects and archives, anywhere in the tree.
213 *.[oa]
214 $ cat Documentation/.gitignore
215 # ignore generated html files,
216 *.html
217 # except foo.html which is maintained by hand
218 !foo.html
219 $ git-ls-files --ignored \
220 --exclude='Documentation/*.[0-9]' \
221 --exclude-from=.git/ignore \
222 --exclude-per-directory=.gitignore
223 --------------------------------------------------------------
224
225
226 See Also
227 --------
228 gitlink:git-read-tree[1]
229
230
231 Author
232 ------
233 Written by Linus Torvalds <torvalds@osdl.org>
234
235 Documentation
236 --------------
237 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
238
239 GIT
240 ---
241 Part of the gitlink:git[7] suite
242