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