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