1git-ls-files(1) 2=============== 3v0.1, May 2005 4 5NAME 6---- 7git-ls-files - Information about files in the cache/working directory 8 9 10SYNOPSIS 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 [--exclude-per-directory=<file>] 18 19DESCRIPTION 20----------- 21This merges the file listing in the directory cache index with the 22actual working directory list, and shows different combinations of the 23two. 24 25One or more of the options below may be used to determine the files 26shown: 27 28OPTIONS 29------- 30-c|--cached:: 31 Show cached files in the output (default) 32 33-d|--deleted:: 34 Show deleted files in the output 35 36-o|--others:: 37 Show other files in the output 38 39-i|--ignored:: 40 Show ignored files in the output 41 Note the this also reverses any exclude list present. 42 43-s|--stage:: 44 Show stage files in the output 45 46-u|--unmerged:: 47 Show unmerged files in the output (forces --stage) 48 49-k|--killed:: 50 Show files on the filesystem that need to be removed due 51 to file/directory conflicts for checkout-cache to 52 succeed. 53 54-z:: 55 \0 line termination on output 56 57-x|--exclude=<pattern>:: 58 Skips files matching pattern. 59 Note that pattern is a shell wildcard pattern. 60 61-X|--exclude-from=<file>:: 62 exclude patterns are read from <file>; 1 per line. 63 64--exclude-per-directory=<file>:: 65 read additional exclude patterns that apply only to the 66 directory and its subdirectories in <file>. 67 68-t:: 69 Identify the file status with the following tags (followed by 70 a space) at the start of each line: 71 H cached 72 M unmerged 73 R removed/deleted 74 K to be killed 75 ? other 76 77Output 78------ 79show files just outputs the filename unless '--stage' is specified in 80which case it outputs: 81 82 [<tag> ]<mode> <object> <stage> <file> 83 84"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine 85detailed information on unmerged paths. 86 87For an unmerged path, instead of recording a single mode/SHA1 pair, 88the dircache records up to three such pairs; one from tree O in stage 891, A in stage 2, and B in stage 3. This information can be used by 90the user (or Cogito) to see what should eventually be recorded at the 91path. (see read-cache for more information on state) 92 93 94Exclude Patterns 95---------------- 96 97'git-ls-files' can use a list of "exclude patterns" when 98traversing the directory tree and finding files to show when the 99flags --others or --ignored are specified. 100 101These exclude patterns come from these places: 102 103 (1) command line flag --exclude=<pattern> specifies a single 104 pattern. 105 106 (2) command line flag --exclude-from=<file> specifies a list of 107 patterns stored in a file. 108 109 (3) command line flag --exclude-per-directory=<name> specifies 110 a name of the file in each directory 'git-ls-files' 111 examines, and if exists, its contents are used as an 112 additional list of patterns. 113 114An exclude pattern file used by (2) and (3) contains one pattern 115per line. A line that starts with a '#' can be used as comment 116for readability. 117 118The list of patterns that is in effect at a given time is 119built and ordered in the following way: 120 121 * --exclude=<pattern> and lines read from --exclude-from=<file> 122 come at the beginning of the list of patterns, in the order 123 given on the command line. Patterns that come from the file 124 specified with --exclude-from are ordered in the same order 125 as they appear in the file. 126 127 * When --exclude-per-directory=<name> is specified, upon 128 entering a directory that has such a file, its contents are 129 appended at the end of the current "list of patterns". They 130 are popped off when leaving the directory. 131 132Each pattern in the pattern list specifies "a match pattern" and 133optionally the fate --- either a file that matches the pattern 134is considered excluded or included. By default, this being 135"exclude" mechanism, the fate is "excluded". A filename is 136examined against the patterns in the list, and the first match 137determines its fate. 138 139A pattern specified on the command line with --exclude or read 140from the file specified with --exclude-from is relative to the 141top of the directory tree. A pattern read from a file specified 142by --exclude-per-directory is relative to the directory that the 143pattern file appears in. 144 145An exclude pattern is of the following format: 146 147 - an optional prefix '!' which means that the fate this pattern 148 specifies is "include", not the usual "exclude"; the 149 remainder of the pattern string is interpreted according to 150 the following rules. 151 152 - if it does not contain a slash '/', it is a shell glob 153 pattern and used to match against the filename without 154 leading directories (i.e. the same way as the current 155 implementation). 156 157 - otherwise, it is a shell glob pattern, suitable for 158 consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a 159 slash in the pattern must match a slash in the pathname. 160 "Documentation/*.html" matches "Documentation/git.html" but 161 not "ppc/ppc.html". As a natural exception, "/*.c" matches 162 "cat-file.c" but not "mozilla-sha1/sha1.c". 163 164An example: 165 166 $ cat .git/ignore 167 # ignore objects and archives, anywhere in the tree. 168 *.[oa] 169 $ cat Documentation/.gitignore 170 # ignore generated html files, 171 # except foo.html which is maintained by hand 172 !foo.html 173 *.html 174 $ git-ls-files --ignored \ 175 --exclude='Documentation/*.[0-9]' \ 176 --exclude-from=.git/ignore \ 177 --exclude-per-directory=.gitignore 178 179 180See Also 181-------- 182link:read-cache.html[read-cache] 183 184 185Author 186------ 187Written by Linus Torvalds <torvalds@osdl.org> 188 189Documentation 190-------------- 191Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 192 193GIT 194--- 195Part of the link:git.html[git] suite 196