1 git-ls-files(1)
2 ===============
4 NAME
5 ----
6 git-ls-files - Show information about files in the index and the working tree
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] [--with-tree=<tree-ish>]
19 [--full-name] [--abbrev] [--] [<file>]\*
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.
27 One or more of the options below may be used to determine the files
28 shown:
30 OPTIONS
31 -------
32 -c|--cached::
33 Show cached files in the output (default)
35 -d|--deleted::
36 Show deleted files in the output
38 -m|--modified::
39 Show modified files in the output
41 -o|--others::
42 Show other files in the output
44 -i|--ignored::
45 Show ignored files in the output.
46 Note that this also reverses any exclude list present.
48 -s|--stage::
49 Show stage files in the output
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.
55 --no-empty-directory::
56 Do not list empty directories. Has no effect without --directory.
58 -u|--unmerged::
59 Show unmerged files in the output (forces --stage)
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.
66 -z::
67 \0 line termination on output.
69 -x|--exclude=<pattern>::
70 Skips files matching pattern.
71 Note that pattern is a shell wildcard pattern.
73 -X|--exclude-from=<file>::
74 exclude patterns are read from <file>; 1 per line.
76 --exclude-per-directory=<file>::
77 read additional exclude patterns that apply only to the
78 directory and its subdirectories in <file>.
80 --error-unmatch::
81 If any <file> does not appear in the index, treat this as an
82 error (return 1).
84 --with-tree=<tree-ish>::
85 When using --error-unmatch to expand the user supplied
86 <file> (i.e. path pattern) arguments to paths, pretend
87 that paths which were removed in the index since the
88 named <tree-ish> are still present. Using this option
89 with `-s` or `-u` options does not make any sense.
91 -t::
92 Identify the file status with the following tags (followed by
93 a space) at the start of each line:
94 H:: cached
95 M:: unmerged
96 R:: removed/deleted
97 C:: modified/changed
98 K:: to be killed
99 ?:: other
101 -v::
102 Similar to `-t`, but use lowercase letters for files
103 that are marked as 'always matching index'.
105 --full-name::
106 When run from a subdirectory, the command usually
107 outputs paths relative to the current directory. This
108 option forces paths to be output relative to the project
109 top directory.
111 --abbrev[=<n>]::
112 Instead of showing the full 40-byte hexadecimal object
113 lines, show only handful hexdigits prefix.
114 Non default number of digits can be specified with --abbrev=<n>.
116 \--::
117 Do not interpret any more arguments as options.
119 <file>::
120 Files to show. If no files are given all files which match the other
121 specified criteria are shown.
123 Output
124 ------
125 show files just outputs the filename unless '--stage' is specified in
126 which case it outputs:
128 [<tag> ]<mode> <object> <stage> <file>
130 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
131 detailed information on unmerged paths.
133 For an unmerged path, instead of recording a single mode/SHA1 pair,
134 the index records up to three such pairs; one from tree O in stage
135 1, A in stage 2, and B in stage 3. This information can be used by
136 the user (or the porcelain) to see what should eventually be recorded at the
137 path. (see git-read-tree for more information on state)
139 When `-z` option is not used, TAB, LF, and backslash characters
140 in pathnames are represented as `\t`, `\n`, and `\\`,
141 respectively.
144 Exclude Patterns
145 ----------------
147 'git-ls-files' can use a list of "exclude patterns" when
148 traversing the directory tree and finding files to show when the
149 flags --others or --ignored are specified. gitlink:gitignore[5]
150 specifies the format of exclude patterns.
152 These exclude patterns come from these places, in order:
154 1. The command line flag --exclude=<pattern> specifies a
155 single pattern. Patterns are ordered in the same order
156 they appear in the command line.
158 2. The command line flag --exclude-from=<file> specifies a
159 file containing a list of patterns. Patterns are ordered
160 in the same order they appear in the file.
162 3. command line flag --exclude-per-directory=<name> specifies
163 a name of the file in each directory 'git-ls-files'
164 examines, normally `.gitignore`. Files in deeper
165 directories take precedence. Patterns are ordered in the
166 same order they appear in the files.
168 A pattern specified on the command line with --exclude or read
169 from the file specified with --exclude-from is relative to the
170 top of the directory tree. A pattern read from a file specified
171 by --exclude-per-directory is relative to the directory that the
172 pattern file appears in.
174 See Also
175 --------
176 gitlink:git-read-tree[1], gitlink:gitignore[5]
179 Author
180 ------
181 Written by Linus Torvalds <torvalds@osdl.org>
183 Documentation
184 --------------
185 Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
187 GIT
188 ---
189 Part of the gitlink:git[7] suite