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