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\--:: 144 Do not interpret any more arguments as options. 145 146<file>:: 147 Files to show. If no files are given all files which match the other 148 specified criteria are shown. 149 150Output 151------ 152'git ls-files' just outputs the filenames unless '--stage' is specified in 153which case it outputs: 154 155 [<tag> ]<mode> <object> <stage> <file> 156 157'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine 158detailed information on unmerged paths. 159 160For an unmerged path, instead of recording a single mode/SHA1 pair, 161the index records up to three such pairs; one from tree O in stage 1621, A in stage 2, and B in stage 3. This information can be used by 163the user (or the porcelain) to see what should eventually be recorded at the 164path. (see linkgit:git-read-tree[1] for more information on state) 165 166When `-z` option is not used, TAB, LF, and backslash characters 167in pathnames are represented as `\t`, `\n`, and `\\`, 168respectively. 169 170 171Exclude Patterns 172---------------- 173 174'git ls-files' can use a list of "exclude patterns" when 175traversing the directory tree and finding files to show when the 176flags --others or --ignored are specified. linkgit:gitignore[5] 177specifies the format of exclude patterns. 178 179These exclude patterns come from these places, in order: 180 181 1. The command line flag --exclude=<pattern> specifies a 182 single pattern. Patterns are ordered in the same order 183 they appear in the command line. 184 185 2. The command line flag --exclude-from=<file> specifies a 186 file containing a list of patterns. Patterns are ordered 187 in the same order they appear in the file. 188 189 3. command line flag --exclude-per-directory=<name> specifies 190 a name of the file in each directory 'git ls-files' 191 examines, normally `.gitignore`. Files in deeper 192 directories take precedence. Patterns are ordered in the 193 same order they appear in the files. 194 195A pattern specified on the command line with --exclude or read 196from the file specified with --exclude-from is relative to the 197top of the directory tree. A pattern read from a file specified 198by --exclude-per-directory is relative to the directory that the 199pattern file appears in. 200 201SEE ALSO 202-------- 203linkgit:git-read-tree[1], linkgit:gitignore[5] 204 205 206Author 207------ 208Written by Linus Torvalds <torvalds@osdl.org> 209 210Documentation 211-------------- 212Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>. 213 214GIT 215--- 216Part of the linkgit:git[1] suite