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