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] [--with-tree=<tree-ish>] 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--with-tree=<tree-ish>:: 85 When using --error-unmatch to expand the user supplied 86 <file> (i.e. path pattern) arguments to paths, pretend 87 that paths which were removed in the index since the 88 named <tree-ish> are still present. Using this option 89 with `-s` or `-u` options does not make any sense. 90 91-t:: 92 Identify the file status with the following tags (followed by 93 a space) at the start of each line: 94 H:: cached 95 M:: unmerged 96 R:: removed/deleted 97 C:: modified/changed 98 K:: to be killed 99 ?:: other 100 101-v:: 102 Similar to `-t`, but use lowercase letters for files 103 that are marked as 'always matching index'. 104 105--full-name:: 106 When run from a subdirectory, the command usually 107 outputs paths relative to the current directory. This 108 option forces paths to be output relative to the project 109 top directory. 110 111--abbrev[=<n>]:: 112 Instead of showing the full 40-byte hexadecimal object 113 lines, show only handful hexdigits prefix. 114 Non default number of digits can be specified with --abbrev=<n>. 115 116\--:: 117 Do not interpret any more arguments as options. 118 119<file>:: 120 Files to show. If no files are given all files which match the other 121 specified criteria are shown. 122 123Output 124------ 125show files just outputs the filename unless '--stage' is specified in 126which case it outputs: 127 128 [<tag> ]<mode> <object> <stage> <file> 129 130"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine 131detailed information on unmerged paths. 132 133For an unmerged path, instead of recording a single mode/SHA1 pair, 134the index records up to three such pairs; one from tree O in stage 1351, A in stage 2, and B in stage 3. This information can be used by 136the user (or the porcelain) to see what should eventually be recorded at the 137path. (see git-read-tree for more information on state) 138 139When `-z` option is not used, TAB, LF, and backslash characters 140in pathnames are represented as `\t`, `\n`, and `\\`, 141respectively. 142 143 144Exclude Patterns 145---------------- 146 147'git-ls-files' can use a list of "exclude patterns" when 148traversing the directory tree and finding files to show when the 149flags --others or --ignored are specified. gitlink:gitignore[5] 150specifies the format of exclude patterns. 151 152These exclude patterns come from these places, in order: 153 154 1. The command line flag --exclude=<pattern> specifies a 155 single pattern. Patterns are ordered in the same order 156 they appear in the command line. 157 158 2. The command line flag --exclude-from=<file> specifies a 159 file containing a list of patterns. Patterns are ordered 160 in the same order they appear in the file. 161 162 3. command line flag --exclude-per-directory=<name> specifies 163 a name of the file in each directory 'git-ls-files' 164 examines, normally `.gitignore`. Files in deeper 165 directories take precedence. Patterns are ordered in the 166 same order they appear in the files. 167 168A pattern specified on the command line with --exclude or read 169from the file specified with --exclude-from is relative to the 170top of the directory tree. A pattern read from a file specified 171by --exclude-per-directory is relative to the directory that the 172pattern file appears in. 173 174See Also 175-------- 176gitlink:git-read-tree[1], gitlink:gitignore[5] 177 178 179Author 180------ 181Written by Linus Torvalds <torvalds@osdl.org> 182 183Documentation 184-------------- 185Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>. 186 187GIT 188--- 189Part of the gitlink:git[7] suite