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