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