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