1git-ls-files(1) 2=============== 3 4NAME 5---- 6git-ls-files - Show information about files in the index and the working tree 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 that 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 index 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. gitlink:gitignore[5] 143specifies the format of exclude patterns. 144 145These exclude patterns come from these places, in order: 146 147 1. The command line flag --exclude=<pattern> specifies a 148 single pattern. Patterns are ordered in the same order 149 they appear in the command line. 150 151 2. The command line flag --exclude-from=<file> specifies a 152 file containing a list of patterns. Patterns are ordered 153 in the same order they appear in the file. 154 155 3. command line flag --exclude-per-directory=<name> specifies 156 a name of the file in each directory 'git-ls-files' 157 examines, normally `.gitignore`. Files in deeper 158 directories take precedence. Patterns are ordered in the 159 same order they appear in the files. 160 161A pattern specified on the command line with --exclude or read 162from the file specified with --exclude-from is relative to the 163top of the directory tree. A pattern read from a file specified 164by --exclude-per-directory is relative to the directory that the 165pattern file appears in. 166 167See Also 168-------- 169gitlink:git-read-tree[1], gitlink:gitignore[5] 170 171 172Author 173------ 174Written by Linus Torvalds <torvalds@osdl.org> 175 176Documentation 177-------------- 178Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>. 179 180GIT 181--- 182Part of the gitlink:git[7] suite