6 git-ls-files - Information about files in the index/working directory
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>]
19 [--full-name] [--abbrev] [--] [<file>]\*
23 This merges the file listing in the directory cache index with the
24 actual working directory list, and shows different combinations of the
27 One or more of the options below may be used to determine the files
33 Show cached files in the output (default)
36 Show deleted files in the output
39 Show modified files in the output
42 Show other files in the output
45 Show ignored files in the output
46 Note the this also reverses any exclude list present.
49 Show stage files in the output
52 If a whole directory is classified as "other", show just its
53 name (with a trailing slash) and not its whole contents.
56 Show unmerged files in the output (forces --stage)
59 Show files on the filesystem that need to be removed due
60 to file/directory conflicts for checkout-index to
64 \0 line termination on output.
66 -x|--exclude=<pattern>::
67 Skips files matching pattern.
68 Note that pattern is a shell wildcard pattern.
70 -X|--exclude-from=<file>::
71 exclude patterns are read from <file>; 1 per line.
73 --exclude-per-directory=<file>::
74 read additional exclude patterns that apply only to the
75 directory and its subdirectories in <file>.
78 If any <file> does not appear in the index, treat this as an
82 Identify the file status with the following tags (followed by
83 a space) at the start of each line:
92 Similar to `-t`, but use lowercase letters for files
93 that are marked as 'always matching index'.
96 When run from a subdirectory, the command usually
97 outputs paths relative to the current directory. This
98 option forces paths to be output relative to the project
102 Instead of showing the full 40-byte hexadecimal object
103 lines, show only handful hexdigits prefix.
104 Non default number of digits can be specified with --abbrev=<n>.
107 Do not interpret any more arguments as options.
110 Files to show. If no files are given all files which match the other
111 specified criteria are shown.
115 show files just outputs the filename unless '--stage' is specified in
116 which case it outputs:
118 [<tag> ]<mode> <object> <stage> <file>
120 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
121 detailed information on unmerged paths.
123 For an unmerged path, instead of recording a single mode/SHA1 pair,
124 the dircache records up to three such pairs; one from tree O in stage
125 1, A in stage 2, and B in stage 3. This information can be used by
126 the user (or the porcelain) to see what should eventually be recorded at the
127 path. (see git-read-tree for more information on state)
129 When `-z` option is not used, TAB, LF, and backslash characters
130 in pathnames are represented as `\t`, `\n`, and `\\`,
137 'git-ls-files' can use a list of "exclude patterns" when
138 traversing the directory tree and finding files to show when the
139 flags --others or --ignored are specified.
141 These exclude patterns come from these places:
143 1. command line flag --exclude=<pattern> specifies a single
146 2. command line flag --exclude-from=<file> specifies a list of
147 patterns stored in a file.
149 3. command line flag --exclude-per-directory=<name> specifies
150 a name of the file in each directory 'git-ls-files'
151 examines, and if exists, its contents are used as an
152 additional list of patterns.
154 An exclude pattern file used by (2) and (3) contains one pattern
155 per line. A line that starts with a '#' can be used as comment
158 There are three lists of patterns that are in effect at a given
159 time. They are built and ordered in the following way:
161 * --exclude=<pattern> from the command line; patterns are
162 ordered in the same order as they appear on the command line.
164 * lines read from --exclude-from=<file>; patterns are ordered
165 in the same order as they appear in the file.
167 * When --exclude-per-directory=<name> is specified, upon
168 entering a directory that has such a file, its contents are
169 appended at the end of the current "list of patterns". They
170 are popped off when leaving the directory.
172 Each pattern in the pattern list specifies "a match pattern" and
173 optionally the fate; either a file that matches the pattern is
174 considered excluded or included. A filename is matched against
175 the patterns in the three lists; the --exclude-from list is
176 checked first, then the --exclude-per-directory list, and then
177 finally the --exclude list. The last match determines its fate.
178 If there is no match in the three lists, the fate is "included".
180 A pattern specified on the command line with --exclude or read
181 from the file specified with --exclude-from is relative to the
182 top of the directory tree. A pattern read from a file specified
183 by --exclude-per-directory is relative to the directory that the
184 pattern file appears in.
186 An exclude pattern is of the following format:
188 - an optional prefix '!' which means that the fate this pattern
189 specifies is "include", not the usual "exclude"; the
190 remainder of the pattern string is interpreted according to
193 - if it does not contain a slash '/', it is a shell glob
194 pattern and used to match against the filename without
195 leading directories (i.e. the same way as the current
198 - otherwise, it is a shell glob pattern, suitable for
199 consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a
200 slash in the pattern must match a slash in the pathname.
201 "Documentation/\*.html" matches "Documentation/git.html" but
202 not "ppc/ppc.html". As a natural exception, "/*.c" matches
203 "cat-file.c" but not "mozilla-sha1/sha1.c".
207 --------------------------------------------------------------
209 # ignore objects and archives, anywhere in the tree.
211 $ cat Documentation/.gitignore
212 # ignore generated html files,
214 # except foo.html which is maintained by hand
216 $ git-ls-files --ignored \
217 --exclude='Documentation/*.[0-9]' \
218 --exclude-from=.git/ignore \
219 --exclude-per-directory=.gitignore
220 --------------------------------------------------------------
225 gitlink:git-read-tree[1]
230 Written by Linus Torvalds <torvalds@osdl.org>
234 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
238 Part of the gitlink:git[7] suite