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