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] [-f] 13 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* 14 (-[c|d|o|i|s|u|k|m])* 15 [--eol] 16 [-x <pattern>|--exclude=<pattern>] 17 [-X <file>|--exclude-from=<file>] 18 [--exclude-per-directory=<file>] 19 [--exclude-standard] 20 [--error-unmatch] [--with-tree=<tree-ish>] 21 [--full-name] [--recurse-submodules] 22 [--abbrev] [--] [<file>...] 23 24DESCRIPTION 25----------- 26This merges the file listing in the directory cache index with the 27actual working directory list, and shows different combinations of the 28two. 29 30One or more of the options below may be used to determine the files 31shown: 32 33OPTIONS 34------- 35-c:: 36--cached:: 37 Show cached files in the output (default) 38 39-d:: 40--deleted:: 41 Show deleted files in the output 42 43-m:: 44--modified:: 45 Show modified files in the output 46 47-o:: 48--others:: 49 Show other (i.e. untracked) files in the output 50 51-i:: 52--ignored:: 53 Show only ignored files in the output. When showing files in the 54 index, print only those matched by an exclude pattern. When 55 showing "other" files, show only those matched by an exclude 56 pattern. 57 58-s:: 59--stage:: 60 Show staged contents' mode bits, object name and stage number in the output. 61 62--directory:: 63 If a whole directory is classified as "other", show just its 64 name (with a trailing slash) and not its whole contents. 65 66--no-empty-directory:: 67 Do not list empty directories. Has no effect without --directory. 68 69-u:: 70--unmerged:: 71 Show unmerged files in the output (forces --stage) 72 73-k:: 74--killed:: 75 Show files on the filesystem that need to be removed due 76 to file/directory conflicts for checkout-index to 77 succeed. 78 79-z:: 80 \0 line termination on output and do not quote filenames. 81 See OUTPUT below for more information. 82 83-x <pattern>:: 84--exclude=<pattern>:: 85 Skip untracked files matching pattern. 86 Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS 87 below for more information. 88 89-X <file>:: 90--exclude-from=<file>:: 91 Read exclude patterns from <file>; 1 per line. 92 93--exclude-per-directory=<file>:: 94 Read additional exclude patterns that apply only to the 95 directory and its subdirectories in <file>. 96 97--exclude-standard:: 98 Add the standard Git exclusions: .git/info/exclude, .gitignore 99 in each directory, and the user's global exclusion file. 100 101--error-unmatch:: 102 If any <file> does not appear in the index, treat this as an 103 error (return 1). 104 105--with-tree=<tree-ish>:: 106 When using --error-unmatch to expand the user supplied 107 <file> (i.e. path pattern) arguments to paths, pretend 108 that paths which were removed in the index since the 109 named <tree-ish> are still present. Using this option 110 with `-s` or `-u` options does not make any sense. 111 112-t:: 113 This feature is semi-deprecated. For scripting purpose, 114 linkgit:git-status[1] `--porcelain` and 115 linkgit:git-diff-files[1] `--name-status` are almost always 116 superior alternatives, and users should look at 117 linkgit:git-status[1] `--short` or linkgit:git-diff[1] 118 `--name-status` for more user-friendly alternatives. 119+ 120This option identifies the file status with the following tags (followed by 121a space) at the start of each line: 122 123 H:: cached 124 S:: skip-worktree 125 M:: unmerged 126 R:: removed/deleted 127 C:: modified/changed 128 K:: to be killed 129 ?:: other 130 131-v:: 132 Similar to `-t`, but use lowercase letters for files 133 that are marked as 'assume unchanged' (see 134 linkgit:git-update-index[1]). 135 136-f:: 137 Similar to `-t`, but use lowercase letters for files 138 that are marked as 'fsmonitor valid' (see 139 linkgit:git-update-index[1]). 140 141--full-name:: 142 When run from a subdirectory, the command usually 143 outputs paths relative to the current directory. This 144 option forces paths to be output relative to the project 145 top directory. 146 147--recurse-submodules:: 148 Recursively calls ls-files on each submodule in the repository. 149 Currently there is only support for the --cached mode. 150 151--abbrev[=<n>]:: 152 Instead of showing the full 40-byte hexadecimal object 153 lines, show only a partial prefix. 154 Non default number of digits can be specified with --abbrev=<n>. 155 156--debug:: 157 After each line that describes a file, add more data about its 158 cache entry. This is intended to show as much information as 159 possible for manual inspection; the exact format may change at 160 any time. 161 162--eol:: 163 Show <eolinfo> and <eolattr> of files. 164 <eolinfo> is the file content identification used by Git when 165 the "text" attribute is "auto" (or not set and core.autocrlf is not false). 166 <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "". 167+ 168"" means the file is not a regular file, it is not in the index or 169not accessible in the working tree. 170+ 171<eolattr> is the attribute that is used when checking out or committing, 172it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". 173Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported. 174+ 175Both the <eolinfo> in the index ("i/<eolinfo>") 176and in the working tree ("w/<eolinfo>") are shown for regular files, 177followed by the ("attr/<eolattr>"). 178 179\--:: 180 Do not interpret any more arguments as options. 181 182<file>:: 183 Files to show. If no files are given all files which match the other 184 specified criteria are shown. 185 186Output 187------ 188'git ls-files' just outputs the filenames unless `--stage` is specified in 189which case it outputs: 190 191 [<tag> ]<mode> <object> <stage> <file> 192 193'git ls-files --eol' will show 194 i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file> 195 196'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine 197detailed information on unmerged paths. 198 199For an unmerged path, instead of recording a single mode/SHA-1 pair, 200the index records up to three such pairs; one from tree O in stage 2011, A in stage 2, and B in stage 3. This information can be used by 202the user (or the porcelain) to see what should eventually be recorded at the 203path. (see linkgit:git-read-tree[1] for more information on state) 204 205Without the `-z` option, pathnames with "unusual" characters are 206quoted as explained for the configuration variable `core.quotePath` 207(see linkgit:git-config[1]). Using `-z` the filename is output 208verbatim and the line is terminated by a NUL byte. 209 210 211Exclude Patterns 212---------------- 213 214'git ls-files' can use a list of "exclude patterns" when 215traversing the directory tree and finding files to show when the 216flags --others or --ignored are specified. linkgit:gitignore[5] 217specifies the format of exclude patterns. 218 219These exclude patterns come from these places, in order: 220 221 1. The command-line flag --exclude=<pattern> specifies a 222 single pattern. Patterns are ordered in the same order 223 they appear in the command line. 224 225 2. The command-line flag --exclude-from=<file> specifies a 226 file containing a list of patterns. Patterns are ordered 227 in the same order they appear in the file. 228 229 3. The command-line flag --exclude-per-directory=<name> specifies 230 a name of the file in each directory 'git ls-files' 231 examines, normally `.gitignore`. Files in deeper 232 directories take precedence. Patterns are ordered in the 233 same order they appear in the files. 234 235A pattern specified on the command line with --exclude or read 236from the file specified with --exclude-from is relative to the 237top of the directory tree. A pattern read from a file specified 238by --exclude-per-directory is relative to the directory that the 239pattern file appears in. 240 241SEE ALSO 242-------- 243linkgit:git-read-tree[1], linkgit:gitignore[5] 244 245GIT 246--- 247Part of the linkgit:git[1] suite