1git-ls-files(1) 2=============== 3 4NAME 5---- 6git-ls-files - Information about files in the index/working directory 7 8 9SYNOPSIS 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] 19 [--full-name] [--abbrev] [--] [<file>]\* 20 21DESCRIPTION 22----------- 23This merges the file listing in the directory cache index with the 24actual working directory list, and shows different combinations of the 25two. 26 27One or more of the options below may be used to determine the files 28shown: 29 30OPTIONS 31------- 32-c|--cached:: 33 Show cached files in the output (default) 34 35-d|--deleted:: 36 Show deleted files in the output 37 38-m|--modified:: 39 Show modified files in the output 40 41-o|--others:: 42 Show other files in the output 43 44-i|--ignored:: 45 Show ignored files in the output 46 Note the this also reverses any exclude list present. 47 48-s|--stage:: 49 Show stage files in the output 50 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. 54 55--no-empty-directory:: 56 Do not list empty directories. Has no effect without --directory. 57 58-u|--unmerged:: 59 Show unmerged files in the output (forces --stage) 60 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. 65 66-z:: 67 \0 line termination on output. 68 69-x|--exclude=<pattern>:: 70 Skips files matching pattern. 71 Note that pattern is a shell wildcard pattern. 72 73-X|--exclude-from=<file>:: 74 exclude patterns are read from <file>; 1 per line. 75 76--exclude-per-directory=<file>:: 77 read additional exclude patterns that apply only to the 78 directory and its subdirectories in <file>. 79 80--error-unmatch:: 81 If any <file> does not appear in the index, treat this as an 82 error (return 1). 83 84-t:: 85 Identify the file status with the following tags (followed by 86 a space) at the start of each line: 87 H:: cached 88 M:: unmerged 89 R:: removed/deleted 90 C:: modified/changed 91 K:: to be killed 92 ?:: other 93 94-v:: 95 Similar to `-t`, but use lowercase letters for files 96 that are marked as 'always matching index'. 97 98--full-name:: 99 When run from a subdirectory, the command usually 100 outputs paths relative to the current directory. This 101 option forces paths to be output relative to the project 102 top directory. 103 104--abbrev[=<n>]:: 105 Instead of showing the full 40-byte hexadecimal object 106 lines, show only handful hexdigits prefix. 107 Non default number of digits can be specified with --abbrev=<n>. 108 109\--:: 110 Do not interpret any more arguments as options. 111 112<file>:: 113 Files to show. If no files are given all files which match the other 114 specified criteria are shown. 115 116Output 117------ 118show files just outputs the filename unless '--stage' is specified in 119which case it outputs: 120 121 [<tag> ]<mode> <object> <stage> <file> 122 123"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine 124detailed information on unmerged paths. 125 126For an unmerged path, instead of recording a single mode/SHA1 pair, 127the dircache records up to three such pairs; one from tree O in stage 1281, A in stage 2, and B in stage 3. This information can be used by 129the user (or the porcelain) to see what should eventually be recorded at the 130path. (see git-read-tree for more information on state) 131 132When `-z` option is not used, TAB, LF, and backslash characters 133in pathnames are represented as `\t`, `\n`, and `\\`, 134respectively. 135 136 137Exclude Patterns 138---------------- 139 140'git-ls-files' can use a list of "exclude patterns" when 141traversing the directory tree and finding files to show when the 142flags --others or --ignored are specified. 143 144These exclude patterns come from these places: 145 146 1. command line flag --exclude=<pattern> specifies a single 147 pattern. 148 149 2. command line flag --exclude-from=<file> specifies a list of 150 patterns stored in a file. 151 152 3. command line flag --exclude-per-directory=<name> specifies 153 a name of the file in each directory 'git-ls-files' 154 examines, and if exists, its contents are used as an 155 additional list of patterns. 156 157An exclude pattern file used by (2) and (3) contains one pattern 158per line. A line that starts with a '#' can be used as comment 159for readability. 160 161There are three lists of patterns that are in effect at a given 162time. They are built and ordered in the following way: 163 164 * --exclude=<pattern> from the command line; patterns are 165 ordered in the same order as they appear on the command line. 166 167 * lines read from --exclude-from=<file>; patterns are ordered 168 in the same order as they appear in the file. 169 170 * When --exclude-per-directory=<name> is specified, upon 171 entering a directory that has such a file, its contents are 172 appended at the end of the current "list of patterns". They 173 are popped off when leaving the directory. 174 175Each pattern in the pattern list specifies "a match pattern" and 176optionally the fate; either a file that matches the pattern is 177considered excluded or included. A filename is matched against 178the patterns in the three lists; the --exclude-from list is 179checked first, then the --exclude-per-directory list, and then 180finally the --exclude list. The last match determines its fate. 181If there is no match in the three lists, the fate is "included". 182 183A pattern specified on the command line with --exclude or read 184from the file specified with --exclude-from is relative to the 185top of the directory tree. A pattern read from a file specified 186by --exclude-per-directory is relative to the directory that the 187pattern file appears in. 188 189An exclude pattern is of the following format: 190 191 - an optional prefix '!' which means that the fate this pattern 192 specifies is "include", not the usual "exclude"; the 193 remainder of the pattern string is interpreted according to 194 the following rules. 195 196 - if it does not contain a slash '/', it is a shell glob 197 pattern and used to match against the filename without 198 leading directories. 199 200 - otherwise, it is a shell glob pattern, suitable for 201 consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a 202 slash in the pattern must match a slash in the pathname. 203 "Documentation/\*.html" matches "Documentation/git.html" but 204 not "ppc/ppc.html". As a natural exception, "/*.c" matches 205 "cat-file.c" but not "mozilla-sha1/sha1.c". 206 207An example: 208 209-------------------------------------------------------------- 210 $ cat .git/info/exclude 211 # ignore objects and archives, anywhere in the tree. 212 *.[oa] 213 $ cat Documentation/.gitignore 214 # ignore generated html files, 215 *.html 216 # except foo.html which is maintained by hand 217 !foo.html 218 $ git-ls-files --ignored \ 219 --exclude='Documentation/*.[0-9]' \ 220 --exclude-from=.git/info/exclude \ 221 --exclude-per-directory=.gitignore 222-------------------------------------------------------------- 223 224Another example: 225 226-------------------------------------------------------------- 227 $ cat .gitignore 228 vmlinux* 229 $ ls arch/foo/kernel/vm* 230 arch/foo/kernel/vmlinux.lds.S 231 $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore 232-------------------------------------------------------------- 233 234The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file 235from getting ignored. 236 237 238See Also 239-------- 240gitlink:git-read-tree[1] 241 242 243Author 244------ 245Written by Linus Torvalds <torvalds@osdl.org> 246 247Documentation 248-------------- 249Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 250 251GIT 252--- 253Part of the gitlink:git[7] suite 254