Do a cross-project merge of Paul Mackerras' gitk visualizer
[git/git.git] / Documentation / git-ls-files.txt
1 git-ls-files(1)
2 ===============
3 v0.1, May 2005
4
5 NAME
6 ----
7 git-ls-files - Information about files in the cache/working directory
8
9
10 SYNOPSIS
11 --------
12 'git-ls-files' [-z] [-t]
13 (--[cached|deleted|others|ignored|stage|unmerged|killed])\*
14 (-[c|d|o|i|s|u|k])\*
15 [-x <pattern>|--exclude=<pattern>]
16 [-X <file>|--exclude-from=<file>]
17
18 DESCRIPTION
19 -----------
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
24 One or more of the options below may be used to determine the files
25 shown:
26
27 OPTIONS
28 -------
29 -c|--cached::
30 Show cached files in the output (default)
31
32 -d|--deleted::
33 Show deleted files in the output
34
35 -o|--others::
36 Show other files in the output
37
38 -i|--ignored::
39 Show ignored files in the output
40 Note the this also reverses any exclude list present.
41
42 -s|--stage::
43 Show stage files in the output
44
45 -u|--unmerged::
46 Show unmerged files in the output (forces --stage)
47
48 -k|--killed::
49 Show files on the filesystem that need to be removed due
50 to file/directory conflicts for checkout-cache to
51 succeed.
52
53 -z::
54 \0 line termination on output
55
56 -x|--exclude=<pattern>::
57 Skips files matching pattern.
58 Note that pattern is a shell wildcard pattern.
59
60 -X|--exclude-from=<file>::
61 exclude patterns are read from <file>; 1 per line.
62 Allows the use of the famous dontdiff file as follows to find
63 out about uncommitted files just as dontdiff is used with
64 the diff command:
65 git-ls-files --others --exclude-from=dontdiff
66
67 -t::
68 Identify the file status with the following tags (followed by
69 a space) at the start of each line:
70 H cached
71 M unmerged
72 R removed/deleted
73 K to be killed
74 ? other
75
76 Output
77 ------
78 show files just outputs the filename unless '--stage' is specified in
79 which case it outputs:
80
81 [<tag> ]<mode> <object> <stage> <file>
82
83 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
84 detailed information on unmerged paths.
85
86 For an unmerged path, instead of recording a single mode/SHA1 pair,
87 the dircache records up to three such pairs; one from tree O in stage
88 1, A in stage 2, and B in stage 3. This information can be used by
89 the user (or Cogito) to see what should eventually be recorded at the
90 path. (see read-cache for more information on state)
91
92 See Also
93 --------
94 link:read-cache.html[read-cache]
95
96
97 Author
98 ------
99 Written by Linus Torvalds <torvalds@osdl.org>
100
101 Documentation
102 --------------
103 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
104
105 GIT
106 ---
107 Part of the link:git.html[git] suite
108