Documentation about exclude/ignore files
[git/git.git] / Documentation / git-ls-files.txt
CommitLineData
2cf565c5
DG
1git-ls-files(1)
2===============
2cf565c5
DG
3
4NAME
5----
5f3aa197 6git-ls-files - Information about files in the index/working directory
2cf565c5
DG
7
8
9SYNOPSIS
10--------
f9666adf
JH
11[verse]
12'git-ls-files' [-z] [-t] [-v]
b0391890
JH
13 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
14 (-[c|d|o|i|s|u|k|m])\*
2cf565c5
DG
15 [-x <pattern>|--exclude=<pattern>]
16 [-X <file>|--exclude-from=<file>]
ad0cae4c 17 [--exclude-per-directory=<file>]
c8af25ca 18 [--error-unmatch]
ad0cae4c 19 [--full-name] [--abbrev] [--] [<file>]\*
2cf565c5
DG
20
21DESCRIPTION
22-----------
23This merges the file listing in the directory cache index with the
24actual working directory list, and shows different combinations of the
25two.
26
27One or more of the options below may be used to determine the files
28shown:
29
30OPTIONS
31-------
32-c|--cached::
33 Show cached files in the output (default)
34
35-d|--deleted::
36 Show deleted files in the output
37
b0391890
JH
38-m|--modified::
39 Show modified files in the output
40
2cf565c5
DG
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
a3259570
PB
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
b0a3de42
PB
55--no-empty-directory::
56 Do not list empty directories. Has no effect without --directory.
57
2cf565c5
DG
58-u|--unmerged::
59 Show unmerged files in the output (forces --stage)
60
6ca45943
JH
61-k|--killed::
62 Show files on the filesystem that need to be removed due
ab182478 63 to file/directory conflicts for checkout-index to
6ca45943
JH
64 succeed.
65
2cf565c5 66-z::
d88156e9 67 \0 line termination on output.
2cf565c5
DG
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.
30b0535f
JH
75
76--exclude-per-directory=<file>::
77 read additional exclude patterns that apply only to the
78 directory and its subdirectories in <file>.
2cf565c5 79
c8af25ca
CW
80--error-unmatch::
81 If any <file> does not appear in the index, treat this as an
82 error (return 1).
83
2cf565c5
DG
84-t::
85 Identify the file status with the following tags (followed by
86 a space) at the start of each line:
df8baa42
JF
87 H:: cached
88 M:: unmerged
89 R:: removed/deleted
89438677 90 C:: modified/changed
df8baa42 91 K:: to be killed
41ac06c7 92 ?:: other
2cf565c5 93
f9666adf
JH
94-v::
95 Similar to `-t`, but use lowercase letters for files
96 that are marked as 'always matching index'.
97
9a84074d
JH
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
ad0cae4c
EW
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
e994004f 109\--::
500b97e4
FK
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
2cf565c5
DG
116Output
117------
118show files just outputs the filename unless '--stage' is specified in
119which 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
124detailed information on unmerged paths.
125
126For an unmerged path, instead of recording a single mode/SHA1 pair,
127the dircache records up to three such pairs; one from tree O in stage
1281, A in stage 2, and B in stage 3. This information can be used by
2c6e4771 129the user (or the porcelain) to see what should eventually be recorded at the
baeda3a7 130path. (see git-read-tree for more information on state)
2cf565c5 131
d88156e9
JH
132When `-z` option is not used, TAB, LF, and backslash characters
133in pathnames are represented as `\t`, `\n`, and `\\`,
134respectively.
135
30b0535f
JH
136
137Exclude Patterns
138----------------
139
140'git-ls-files' can use a list of "exclude patterns" when
141traversing the directory tree and finding files to show when the
142flags --others or --ignored are specified.
143
144These exclude patterns come from these places:
145
df8baa42 146 1. command line flag --exclude=<pattern> specifies a single
30b0535f
JH
147 pattern.
148
df8baa42 149 2. command line flag --exclude-from=<file> specifies a list of
30b0535f
JH
150 patterns stored in a file.
151
df8baa42 152 3. command line flag --exclude-per-directory=<name> specifies
30b0535f
JH
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
157An exclude pattern file used by (2) and (3) contains one pattern
158per line. A line that starts with a '#' can be used as comment
159for readability.
160
1df092d2
JH
161There are three lists of patterns that are in effect at a given
162time. They are built and ordered in the following way:
30b0535f 163
1df092d2
JH
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.
30b0535f
JH
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
175Each pattern in the pattern list specifies "a match pattern" and
2c6e4771 176optionally the fate; either a file that matches the pattern is
1df092d2
JH
177considered excluded or included. A filename is matched against
178the patterns in the three lists; the --exclude-from list is
179checked first, then the --exclude-per-directory list, and then
180finally the --exclude list. The last match determines its fate.
181If there is no match in the three lists, the fate is "included".
30b0535f
JH
182
183A pattern specified on the command line with --exclude or read
184from the file specified with --exclude-from is relative to the
185top of the directory tree. A pattern read from a file specified
186by --exclude-per-directory is relative to the directory that the
187pattern file appears in.
188
189An 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
b86bec6c 198 leading directories.
30b0535f
JH
199
200 - otherwise, it is a shell glob pattern, suitable for
201 consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a
202 slash in the pattern must match a slash in the pathname.
df8baa42 203 "Documentation/\*.html" matches "Documentation/git.html" but
30b0535f
JH
204 not "ppc/ppc.html". As a natural exception, "/*.c" matches
205 "cat-file.c" but not "mozilla-sha1/sha1.c".
206
207An example:
208
df8baa42 209--------------------------------------------------------------
ff4d7804 210 $ cat .git/info/exclude
30b0535f
JH
211 # ignore objects and archives, anywhere in the tree.
212 *.[oa]
213 $ cat Documentation/.gitignore
214 # ignore generated html files,
1df092d2 215 *.html
30b0535f
JH
216 # except foo.html which is maintained by hand
217 !foo.html
30b0535f
JH
218 $ git-ls-files --ignored \
219 --exclude='Documentation/*.[0-9]' \
ff4d7804 220 --exclude-from=.git/info/exclude \
30b0535f 221 --exclude-per-directory=.gitignore
df8baa42 222--------------------------------------------------------------
30b0535f 223
b86bec6c
JH
224Another example:
225
226--------------------------------------------------------------
227 $ cat .gitignore
228 vmlinux*
229 $ ls arch/foo/kernel/vm*
230 arch/foo/kernel/vmlinux.lds.S
231 $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
232--------------------------------------------------------------
233
234The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file
235from getting ignored.
236
30b0535f 237
c1bdacf9
DG
238See Also
239--------
a7154e91 240gitlink:git-read-tree[1]
2cf565c5
DG
241
242
243Author
244------
245Written by Linus Torvalds <torvalds@osdl.org>
246
247Documentation
248--------------
249Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
250
251GIT
252---
a7154e91 253Part of the gitlink:git[7] suite
2cf565c5 254