1GIT-LS-FILES(1) Git Manual GIT-LS-FILES(1)
2
6 git-ls-files - Show information about files in the index and the
7 working tree
8
10 git-ls-files [-z] [-t] [-v]
11 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
12 (-[c|d|o|i|s|u|k|m])*
13 [-x <pattern>|--exclude=<pattern>]
14 [-X <file>|--exclude-from=<file>]
15 [--exclude-per-directory=<file>]
16 [--error-unmatch] [--with-tree=<tree-ish>]
17 [--full-name] [--abbrev] [--] [<file>]*
18
20 This merges the file listing in the directory cache index with the
21 actual working directory list, and shows different combinations of the
22 two.
23 One or more of the options below may be used to determine the files
25 shown:
26
28 -c|--cached
29 Show cached files in the output (default)
30 -d|--deleted
32 Show deleted files in the output
33 -m|--modified
35 Show modified files in the output
36 -o|--others
38 Show other files in the output
39 -i|--ignored
41 Show ignored files in the output. Note that this also reverses any
42 exclude list present.
43 -s|--stage
45 Show stage files in the output
46 --directory
48 If a whole directory is classified as "other", show just its name
49 (with a trailing slash) and not its whole contents.
50 --no-empty-directory
52 Do not list empty directories. Has no effect without --directory.
53 -u|--unmerged
55 Show unmerged files in the output (forces --stage)
56 -k|--killed
58 Show files on the filesystem that need to be removed due to
59 file/directory conflicts for checkout-index to succeed.
60 -z
62 \0 line termination on output.
63 -x|--exclude=<pattern>
65 Skips files matching pattern. Note that pattern is a shell wildcard
66 pattern.
67 -X|--exclude-from=<file>
69 exclude patterns are read from <file>; 1 per line.
70 --exclude-per-directory=<file>
72 read additional exclude patterns that apply only to the directory
73 and its subdirectories in <file>.
74 --error-unmatch
76 If any <file> does not appear in the index, treat this as an error
77 (return 1).
78 --with-tree=<tree-ish>
80 When using --error-unmatch to expand the user supplied <file> (i.e.
81 path pattern) arguments to paths, pretend that paths which were
82 removed in the index since the named <tree-ish> are still present.
83 Using this option with -s or -u options does not make any sense.
84 -t
86 Identify the file status with the following tags (followed by a
87 space) at the start of each line:
88 H cached
90 M unmerged
91 R removed/deleted
92 C modified/changed
93 K to be killed
94 ? other
95 -v
98 Similar to -t, but use lowercase letters for files that are marked
99 as always matching index.
100 --full-name
102 When run from a subdirectory, the command usually outputs paths
103 relative to the current directory. This option forces paths to be
104 output relative to the project top directory.
105 --abbrev[=<n>]
107 Instead of showing the full 40-byte hexadecimal object lines, show
108 only handful hexdigits prefix. Non default number of digits can be
109 specified with --abbrev=<n>.
110 --
112 Do not interpret any more arguments as options.
113 <file>
115 Files to show. If no files are given all files which match the
116 other specified criteria are shown.
117
119 show files just outputs the filename unless --stage is specified in
120 which case it outputs:
121 [<tag> ]<mode> <object> <stage> <file>
124 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to
125 examine detailed information on unmerged paths.
126 For an unmerged path, instead of recording a single mode/SHA1 pair, the
128 index records up to three such pairs; one from tree O in stage 1, A in
129 stage 2, and B in stage 3. This information can be used by the user (or
130 the porcelain) to see what should eventually be recorded at the path.
131 (see git-read-tree for more information on state)
132 When -z option is not used, TAB, LF, and backslash characters in
134 pathnames are represented as \t, \n, and \\, respectively.
135
137 git-ls-files can use a list of "exclude patterns" when traversing the
138 directory tree and finding files to show when the flags --others or
139 --ignored are specified. gitignore(5) specifies the format of exclude
140 patterns.
141 These exclude patterns come from these places, in order:
143 1. The command line flag --exclude=<pattern> specifies a single
146 pattern. Patterns are ordered in the same order they appear in the
147 command line.
148 2. The command line flag --exclude-from=<file> specifies a file
150 containing a list of patterns. Patterns are ordered in the same
151 order they appear in the file.
152 3. command line flag --exclude-per-directory=<name> specifies a name
154 of the file in each directory git-ls-files examines, normally
155 .gitignore. Files in deeper directories take precedence. Patterns
156 are ordered in the same order they appear in the files.
157 A pattern specified on the command line with --exclude or read from the
158 file specified with --exclude-from is relative to the top of the
159 directory tree. A pattern read from a file specified by
160 --exclude-per-directory is relative to the directory that the pattern
161 file appears in.
162
164 git-read-tree(1), gitignore(5)
165
167 Written by Linus Torvalds <torvalds@osdl.org>
168
170 Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the
171 git-list <git@vger.kernel.org>.
172
174 Part of the git(7) suite
175Git 1.5.3.3 10/09/2007 GIT-LS-FILES(1)