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