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