Merge branch 'rj/tap-fix'
[git/mjg.git] / Documentation / git-ls-files.txt
blob4b28292811ce019fc94259849f8c5ad6d514b686
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                 [--exclude-standard]
19                 [--error-unmatch] [--with-tree=<tree-ish>]
20                 [--full-name] [--abbrev] [--] [<file>...]
22 DESCRIPTION
23 -----------
24 This merges the file listing in the directory cache index with the
25 actual working directory list, and shows different combinations of the
26 two.
28 One or more of the options below may be used to determine the files
29 shown:
31 OPTIONS
32 -------
33 -c::
34 --cached::
35         Show cached files in the output (default)
37 -d::
38 --deleted::
39         Show deleted files in the output
41 -m::
42 --modified::
43         Show modified files in the output
45 -o::
46 --others::
47         Show other (i.e. untracked) files in the output
49 -i::
50 --ignored::
51         Show only ignored files in the output. When showing files in the
52         index, print only those matched by an exclude pattern. When
53         showing "other" files, show only those matched by an exclude
54         pattern.
56 -s::
57 --stage::
58         Show staged contents' object name, mode bits and stage number in the output.
60 --directory::
61         If a whole directory is classified as "other", show just its
62         name (with a trailing slash) and not its whole contents.
64 --no-empty-directory::
65         Do not list empty directories. Has no effect without --directory.
67 -u::
68 --unmerged::
69         Show unmerged files in the output (forces --stage)
71 -k::
72 --killed::
73         Show files on the filesystem that need to be removed due
74         to file/directory conflicts for checkout-index to
75         succeed.
77 -z::
78         \0 line termination on output.
80 -x <pattern>::
81 --exclude=<pattern>::
82         Skip untracked files matching pattern.
83         Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS
84         below for more information.
86 -X <file>::
87 --exclude-from=<file>::
88         Read exclude patterns from <file>; 1 per line.
90 --exclude-per-directory=<file>::
91         Read additional exclude patterns that apply only to the
92         directory and its subdirectories in <file>.
94 --exclude-standard::
95         Add the standard git exclusions: .git/info/exclude, .gitignore
96         in each directory, and the user's global exclusion file.
98 --error-unmatch::
99         If any <file> does not appear in the index, treat this as an
100         error (return 1).
102 --with-tree=<tree-ish>::
103         When using --error-unmatch to expand the user supplied
104         <file> (i.e. path pattern) arguments to paths, pretend
105         that paths which were removed in the index since the
106         named <tree-ish> are still present.  Using this option
107         with `-s` or `-u` options does not make any sense.
109 -t::
110         This feature is semi-deprecated. For scripting purpose,
111         linkgit:git-status[1] `--porcelain` and
112         linkgit:git-diff-files[1] `--name-status` are almost always
113         superior alternatives, and users should look at
114         linkgit:git-status[1] `--short` or linkgit:git-diff[1]
115         `--name-status` for more user-friendly alternatives.
117 This option identifies the file status with the following tags (followed by
118 a space) at the start of each line:
120         H::     cached
121         S::     skip-worktree
122         M::     unmerged
123         R::     removed/deleted
124         C::     modified/changed
125         K::     to be killed
126         ?::     other
128 -v::
129         Similar to `-t`, but use lowercase letters for files
130         that are marked as 'assume unchanged' (see
131         linkgit:git-update-index[1]).
133 --full-name::
134         When run from a subdirectory, the command usually
135         outputs paths relative to the current directory.  This
136         option forces paths to be output relative to the project
137         top directory.
139 --abbrev[=<n>]::
140         Instead of showing the full 40-byte hexadecimal object
141         lines, show only a partial prefix.
142         Non default number of digits can be specified with --abbrev=<n>.
144 --debug::
145         After each line that describes a file, add more data about its
146         cache entry.  This is intended to show as much information as
147         possible for manual inspection; the exact format may change at
148         any time.
150 \--::
151         Do not interpret any more arguments as options.
153 <file>::
154         Files to show. If no files are given all files which match the other
155         specified criteria are shown.
157 Output
158 ------
159 'git ls-files' just outputs the filenames unless '--stage' is specified in
160 which case it outputs:
162         [<tag> ]<mode> <object> <stage> <file>
164 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine
165 detailed information on unmerged paths.
167 For an unmerged path, instead of recording a single mode/SHA1 pair,
168 the index records up to three such pairs; one from tree O in stage
169 1, A in stage 2, and B in stage 3.  This information can be used by
170 the user (or the porcelain) to see what should eventually be recorded at the
171 path. (see linkgit:git-read-tree[1] for more information on state)
173 When `-z` option is not used, TAB, LF, and backslash characters
174 in pathnames are represented as `\t`, `\n`, and `\\`,
175 respectively.
178 Exclude Patterns
179 ----------------
181 'git ls-files' can use a list of "exclude patterns" when
182 traversing the directory tree and finding files to show when the
183 flags --others or --ignored are specified.  linkgit:gitignore[5]
184 specifies the format of exclude patterns.
186 These exclude patterns come from these places, in order:
188   1. The command line flag --exclude=<pattern> specifies a
189      single pattern.  Patterns are ordered in the same order
190      they appear in the command line.
192   2. The command line flag --exclude-from=<file> specifies a
193      file containing a list of patterns.  Patterns are ordered
194      in the same order they appear in the file.
196   3. The command line flag --exclude-per-directory=<name> specifies
197      a name of the file in each directory 'git ls-files'
198      examines, normally `.gitignore`.  Files in deeper
199      directories take precedence.  Patterns are ordered in the
200      same order they appear in the files.
202 A pattern specified on the command line with --exclude or read
203 from the file specified with --exclude-from is relative to the
204 top of the directory tree.  A pattern read from a file specified
205 by --exclude-per-directory is relative to the directory that the
206 pattern file appears in.
208 SEE ALSO
209 --------
210 linkgit:git-read-tree[1], linkgit:gitignore[5]
214 Part of the linkgit:git[1] suite