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