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 [--exclude-standard] 19 [--error-unmatch] [--with-tree=<tree-ish>] 20 [--full-name] [--abbrev] [--] [<file>]\* 21 22DESCRIPTION 23----------- 24This merges the file listing in the directory cache index with the 25actual working directory list, and shows different combinations of the 26two. 27 28One or more of the options below may be used to determine the files 29shown: 30 31OPTIONS 32------- 33-c|--cached:: 34 Show cached files in the output (default) 35 36-d|--deleted:: 37 Show deleted files in the output 38 39-m|--modified:: 40 Show modified files in the output 41 42-o|--others:: 43 Show other files in the output 44 45-i|--ignored:: 46 Show ignored files in the output. 47 Note that this also reverses any exclude list present. 48 49-s|--stage:: 50 Show stage files in the output 51 52--directory:: 53 If a whole directory is classified as "other", show just its 54 name (with a trailing slash) and not its whole contents. 55 56--no-empty-directory:: 57 Do not list empty directories. Has no effect without --directory. 58 59-u|--unmerged:: 60 Show unmerged files in the output (forces --stage) 61 62-k|--killed:: 63 Show files on the filesystem that need to be removed due 64 to file/directory conflicts for checkout-index to 65 succeed. 66 67-z:: 68 \0 line termination on output. 69 70-x|--exclude=<pattern>:: 71 Skips files matching pattern. 72 Note that pattern is a shell wildcard pattern. 73 74-X|--exclude-from=<file>:: 75 exclude patterns are read from <file>; 1 per line. 76 77--exclude-per-directory=<file>:: 78 read additional exclude patterns that apply only to the 79 directory and its subdirectories in <file>. 80 81--exclude-standard:: 82 Add the standard git exclusions: .git/info/exclude, .gitignore 83 in each directory, and the user's global exclusion file. 84 85--error-unmatch:: 86 If any <file> does not appear in the index, treat this as an 87 error (return 1). 88 89--with-tree=<tree-ish>:: 90 When using --error-unmatch to expand the user supplied 91 <file> (i.e. path pattern) arguments to paths, pretend 92 that paths which were removed in the index since the 93 named <tree-ish> are still present. Using this option 94 with `-s` or `-u` options does not make any sense. 95 96-t:: 97 Identify the file status with the following tags (followed by 98 a space) at the start of each line: 99 H:: cached 100 M:: unmerged 101 R:: removed/deleted 102 C:: modified/changed 103 K:: to be killed 104 ?:: other 105 106-v:: 107 Similar to `-t`, but use lowercase letters for files 108 that are marked as 'always matching index'. 109 110--full-name:: 111 When run from a subdirectory, the command usually 112 outputs paths relative to the current directory. This 113 option forces paths to be output relative to the project 114 top directory. 115 116--abbrev[=<n>]:: 117 Instead of showing the full 40-byte hexadecimal object 118 lines, show only handful hexdigits prefix. 119 Non default number of digits can be specified with --abbrev=<n>. 120 121\--:: 122 Do not interpret any more arguments as options. 123 124<file>:: 125 Files to show. If no files are given all files which match the other 126 specified criteria are shown. 127 128Output 129------ 130show files just outputs the filename unless '--stage' is specified in 131which case it outputs: 132 133 [<tag> ]<mode> <object> <stage> <file> 134 135"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine 136detailed information on unmerged paths. 137 138For an unmerged path, instead of recording a single mode/SHA1 pair, 139the index records up to three such pairs; one from tree O in stage 1401, A in stage 2, and B in stage 3. This information can be used by 141the user (or the porcelain) to see what should eventually be recorded at the 142path. (see git-read-tree for more information on state) 143 144When `-z` option is not used, TAB, LF, and backslash characters 145in pathnames are represented as `\t`, `\n`, and `\\`, 146respectively. 147 148 149Exclude Patterns 150---------------- 151 152'git-ls-files' can use a list of "exclude patterns" when 153traversing the directory tree and finding files to show when the 154flags --others or --ignored are specified. gitlink:gitignore[5] 155specifies the format of exclude patterns. 156 157These exclude patterns come from these places, in order: 158 159 1. The command line flag --exclude=<pattern> specifies a 160 single pattern. Patterns are ordered in the same order 161 they appear in the command line. 162 163 2. The command line flag --exclude-from=<file> specifies a 164 file containing a list of patterns. Patterns are ordered 165 in the same order they appear in the file. 166 167 3. command line flag --exclude-per-directory=<name> specifies 168 a name of the file in each directory 'git-ls-files' 169 examines, normally `.gitignore`. Files in deeper 170 directories take precedence. Patterns are ordered in the 171 same order they appear in the files. 172 173A pattern specified on the command line with --exclude or read 174from the file specified with --exclude-from is relative to the 175top of the directory tree. A pattern read from a file specified 176by --exclude-per-directory is relative to the directory that the 177pattern file appears in. 178 179See Also 180-------- 181gitlink:git-read-tree[1], gitlink:gitignore[5] 182 183 184Author 185------ 186Written by Linus Torvalds <torvalds@osdl.org> 187 188Documentation 189-------------- 190Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>. 191 192GIT 193--- 194Part of the gitlink:git[7] suite