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 'assume unchanged' (see 109 linkgit:git-update-index[1]). 110 111--full-name:: 112 When run from a subdirectory, the command usually 113 outputs paths relative to the current directory. This 114 option forces paths to be output relative to the project 115 top directory. 116 117--abbrev[=<n>]:: 118 Instead of showing the full 40-byte hexadecimal object 119 lines, show only handful hexdigits prefix. 120 Non default number of digits can be specified with --abbrev=<n>. 121 122\--:: 123 Do not interpret any more arguments as options. 124 125<file>:: 126 Files to show. If no files are given all files which match the other 127 specified criteria are shown. 128 129Output 130------ 131show files just outputs the filename unless '--stage' is specified in 132which case it outputs: 133 134 [<tag> ]<mode> <object> <stage> <file> 135 136"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine 137detailed information on unmerged paths. 138 139For an unmerged path, instead of recording a single mode/SHA1 pair, 140the index records up to three such pairs; one from tree O in stage 1411, A in stage 2, and B in stage 3. This information can be used by 142the user (or the porcelain) to see what should eventually be recorded at the 143path. (see git-read-tree for more information on state) 144 145When `-z` option is not used, TAB, LF, and backslash characters 146in pathnames are represented as `\t`, `\n`, and `\\`, 147respectively. 148 149 150Exclude Patterns 151---------------- 152 153'git-ls-files' can use a list of "exclude patterns" when 154traversing the directory tree and finding files to show when the 155flags --others or --ignored are specified. linkgit:gitignore[5] 156specifies the format of exclude patterns. 157 158These exclude patterns come from these places, in order: 159 160 1. The command line flag --exclude=<pattern> specifies a 161 single pattern. Patterns are ordered in the same order 162 they appear in the command line. 163 164 2. The command line flag --exclude-from=<file> specifies a 165 file containing a list of patterns. Patterns are ordered 166 in the same order they appear in the file. 167 168 3. command line flag --exclude-per-directory=<name> specifies 169 a name of the file in each directory 'git-ls-files' 170 examines, normally `.gitignore`. Files in deeper 171 directories take precedence. Patterns are ordered in the 172 same order they appear in the files. 173 174A pattern specified on the command line with --exclude or read 175from the file specified with --exclude-from is relative to the 176top of the directory tree. A pattern read from a file specified 177by --exclude-per-directory is relative to the directory that the 178pattern file appears in. 179 180See Also 181-------- 182linkgit:git-read-tree[1], linkgit:gitignore[5] 183 184 185Author 186------ 187Written by Linus Torvalds <torvalds@osdl.org> 188 189Documentation 190-------------- 191Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>. 192 193GIT 194--- 195Part of the linkgit:git[7] suite