| 1 | git-ls-files(1) |
| 2 | =============== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-ls-files - Show information about files in the index and the working tree |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git ls-files' [-z] [-t] [-v] [-f] |
| 13 | [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored] |
| 14 | [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified] |
| 15 | [--resolve-undo] |
| 16 | [--directory [--no-empty-directory]] [--eol] |
| 17 | [--deduplicate] |
| 18 | [-x <pattern>|--exclude=<pattern>] |
| 19 | [-X <file>|--exclude-from=<file>] |
| 20 | [--exclude-per-directory=<file>] |
| 21 | [--exclude-standard] |
| 22 | [--error-unmatch] [--with-tree=<tree-ish>] |
| 23 | [--full-name] [--recurse-submodules] |
| 24 | [--abbrev[=<n>]] [--format=<format>] [--] [<file>...] |
| 25 | |
| 26 | DESCRIPTION |
| 27 | ----------- |
| 28 | This command merges the file listing in the index with the actual working |
| 29 | directory list, and shows different combinations of the two. |
| 30 | |
| 31 | Several flags can be used to determine which files are |
| 32 | shown, and each file may be printed multiple times if there are |
| 33 | multiple entries in the index or if multiple statuses are applicable for |
| 34 | the relevant file selection options. |
| 35 | |
| 36 | OPTIONS |
| 37 | ------- |
| 38 | -c:: |
| 39 | --cached:: |
| 40 | Show all files cached in Git's index, i.e. all tracked files. |
| 41 | (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo |
| 42 | options are specified.) |
| 43 | |
| 44 | -d:: |
| 45 | --deleted:: |
| 46 | Show files with an unstaged deletion |
| 47 | |
| 48 | -m:: |
| 49 | --modified:: |
| 50 | Show files with an unstaged modification (note that an unstaged |
| 51 | deletion also counts as an unstaged modification) |
| 52 | |
| 53 | -o:: |
| 54 | --others:: |
| 55 | Show other (i.e. untracked) files in the output |
| 56 | |
| 57 | -i:: |
| 58 | --ignored:: |
| 59 | Show only ignored files in the output. Must be used with |
| 60 | either an explicit '-c' or '-o'. When showing files in the |
| 61 | index (i.e. when used with '-c'), print only those files |
| 62 | matching an exclude pattern. When showing "other" files |
| 63 | (i.e. when used with '-o'), show only those matched by an |
| 64 | exclude pattern. Standard ignore rules are not automatically |
| 65 | activated; therefore, at least one of the `--exclude*` options |
| 66 | is required. |
| 67 | |
| 68 | -s:: |
| 69 | --stage:: |
| 70 | Show staged contents' mode bits, object name and stage number in the output. |
| 71 | |
| 72 | --directory:: |
| 73 | If a whole directory is classified as "other", show just its |
| 74 | name (with a trailing slash) and not its whole contents. |
| 75 | Has no effect without -o/--others. |
| 76 | |
| 77 | --no-empty-directory:: |
| 78 | Do not list empty directories. Has no effect without --directory. |
| 79 | |
| 80 | -u:: |
| 81 | --unmerged:: |
| 82 | Show information about unmerged files in the output, but do |
| 83 | not show any other tracked files (forces --stage, overrides |
| 84 | --cached). |
| 85 | |
| 86 | -k:: |
| 87 | --killed:: |
| 88 | Show untracked files on the filesystem that need to be removed |
| 89 | due to file/directory conflicts for tracked files to be able to |
| 90 | be written to the filesystem. |
| 91 | |
| 92 | --resolve-undo:: |
| 93 | Show files having resolve-undo information in the index |
| 94 | together with their resolve-undo information. (resolve-undo |
| 95 | information is what is used to implement "git checkout -m |
| 96 | $PATH", i.e. to recreate merge conflicts that were |
| 97 | accidentally resolved) |
| 98 | |
| 99 | -z:: |
| 100 | \0 line termination on output and do not quote filenames. |
| 101 | See OUTPUT below for more information. |
| 102 | |
| 103 | --deduplicate:: |
| 104 | When only filenames are shown, suppress duplicates that may |
| 105 | come from having multiple stages during a merge, or giving |
| 106 | `--deleted` and `--modified` option at the same time. |
| 107 | When any of the `-t`, `--unmerged`, or `--stage` option is |
| 108 | in use, this option has no effect. |
| 109 | |
| 110 | -x <pattern>:: |
| 111 | --exclude=<pattern>:: |
| 112 | Skip untracked files matching pattern. |
| 113 | Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS |
| 114 | below for more information. |
| 115 | |
| 116 | -X <file>:: |
| 117 | --exclude-from=<file>:: |
| 118 | Read exclude patterns from <file>; 1 per line. |
| 119 | |
| 120 | --exclude-per-directory=<file>:: |
| 121 | Read additional exclude patterns that apply only to the |
| 122 | directory and its subdirectories in <file>. If you are |
| 123 | trying to emulate the way Porcelain commands work, using |
| 124 | the `--exclude-standard` option instead is easier and more |
| 125 | thorough. |
| 126 | |
| 127 | --exclude-standard:: |
| 128 | Add the standard Git exclusions: .git/info/exclude, .gitignore |
| 129 | in each directory, and the user's global exclusion file. |
| 130 | |
| 131 | --error-unmatch:: |
| 132 | If any <file> does not appear in the index, treat this as an |
| 133 | error (return 1). |
| 134 | |
| 135 | --with-tree=<tree-ish>:: |
| 136 | When using --error-unmatch to expand the user supplied |
| 137 | <file> (i.e. path pattern) arguments to paths, pretend |
| 138 | that paths which were removed in the index since the |
| 139 | named <tree-ish> are still present. Using this option |
| 140 | with `-s` or `-u` options does not make any sense. |
| 141 | |
| 142 | -t:: |
| 143 | Show status tags together with filenames. Note that for |
| 144 | scripting purposes, linkgit:git-status[1] `--porcelain` and |
| 145 | linkgit:git-diff-files[1] `--name-status` are almost always |
| 146 | superior alternatives; users should look at |
| 147 | linkgit:git-status[1] `--short` or linkgit:git-diff[1] |
| 148 | `--name-status` for more user-friendly alternatives. |
| 149 | + |
| 150 | -- |
| 151 | This option provides a reason for showing each filename, in the form |
| 152 | of a status tag (which is followed by a space and then the filename). |
| 153 | The status tags are all single characters from the following list: |
| 154 | |
| 155 | H:: tracked file that is not either unmerged or skip-worktree |
| 156 | S:: tracked file that is skip-worktree |
| 157 | M:: tracked file that is unmerged |
| 158 | R:: tracked file with unstaged removal/deletion |
| 159 | C:: tracked file with unstaged modification/change |
| 160 | K:: untracked paths which are part of file/directory conflicts |
| 161 | which prevent checking out tracked files |
| 162 | ?:: untracked file |
| 163 | U:: file with resolve-undo information |
| 164 | -- |
| 165 | |
| 166 | -v:: |
| 167 | Similar to `-t`, but use lowercase letters for files |
| 168 | that are marked as 'assume unchanged' (see |
| 169 | linkgit:git-update-index[1]). |
| 170 | |
| 171 | -f:: |
| 172 | Similar to `-t`, but use lowercase letters for files |
| 173 | that are marked as 'fsmonitor valid' (see |
| 174 | linkgit:git-update-index[1]). |
| 175 | |
| 176 | --full-name:: |
| 177 | When run from a subdirectory, the command usually |
| 178 | outputs paths relative to the current directory. This |
| 179 | option forces paths to be output relative to the project |
| 180 | top directory. |
| 181 | |
| 182 | --recurse-submodules:: |
| 183 | Recursively calls ls-files on each active submodule in the repository. |
| 184 | Currently there is only support for the --cached and --stage modes. |
| 185 | |
| 186 | --abbrev[=<n>]:: |
| 187 | Instead of showing the full 40-byte hexadecimal object |
| 188 | lines, show the shortest prefix that is at least '<n>' |
| 189 | hexdigits long that uniquely refers the object. |
| 190 | Non default number of digits can be specified with --abbrev=<n>. |
| 191 | |
| 192 | --debug:: |
| 193 | After each line that describes a file, add more data about its |
| 194 | cache entry. This is intended to show as much information as |
| 195 | possible for manual inspection; the exact format may change at |
| 196 | any time. |
| 197 | |
| 198 | --eol:: |
| 199 | Show <eolinfo> and <eolattr> of files. |
| 200 | <eolinfo> is the file content identification used by Git when |
| 201 | the "text" attribute is "auto" (or not set and core.autocrlf is not false). |
| 202 | <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "". |
| 203 | + |
| 204 | "" means the file is not a regular file, it is not in the index or |
| 205 | not accessible in the working tree. |
| 206 | + |
| 207 | <eolattr> is the attribute that is used when checking out or committing, |
| 208 | it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". |
| 209 | Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported. |
| 210 | + |
| 211 | Both the <eolinfo> in the index ("i/<eolinfo>") |
| 212 | and in the working tree ("w/<eolinfo>") are shown for regular files, |
| 213 | followed by the ("attr/<eolattr>"). |
| 214 | |
| 215 | --sparse:: |
| 216 | If the index is sparse, show the sparse directories without expanding |
| 217 | to the contained files. Sparse directories will be shown with a |
| 218 | trailing slash, such as "x/" for a sparse directory "x". |
| 219 | |
| 220 | --format=<format>:: |
| 221 | A string that interpolates `%(fieldname)` from the result being shown. |
| 222 | It also interpolates `%%` to `%`, and `%xXX` where `XX` are hex digits |
| 223 | interpolates to character with hex code `XX`; for example `%x00` |
| 224 | interpolates to `\0` (NUL), `%x09` to `\t` (TAB) and %x0a to `\n` (LF). |
| 225 | --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo` |
| 226 | and `--eol`. |
| 227 | \--:: |
| 228 | Do not interpret any more arguments as options. |
| 229 | |
| 230 | <file>:: |
| 231 | Files to show. If no files are given all files which match the other |
| 232 | specified criteria are shown. |
| 233 | |
| 234 | OUTPUT |
| 235 | ------ |
| 236 | 'git ls-files' just outputs the filenames unless `--stage` is specified in |
| 237 | which case it outputs: |
| 238 | |
| 239 | [<tag> ]<mode> <object> <stage> <file> |
| 240 | |
| 241 | 'git ls-files --eol' will show |
| 242 | i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file> |
| 243 | |
| 244 | 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine |
| 245 | detailed information on unmerged paths. |
| 246 | |
| 247 | For an unmerged path, instead of recording a single mode/SHA-1 pair, |
| 248 | the index records up to three such pairs; one from tree O in stage |
| 249 | 1, A in stage 2, and B in stage 3. This information can be used by |
| 250 | the user (or the porcelain) to see what should eventually be recorded at the |
| 251 | path. (see linkgit:git-read-tree[1] for more information on state) |
| 252 | |
| 253 | Without the `-z` option, pathnames with "unusual" characters are |
| 254 | quoted as explained for the configuration variable `core.quotePath` |
| 255 | (see linkgit:git-config[1]). Using `-z` the filename is output |
| 256 | verbatim and the line is terminated by a NUL byte. |
| 257 | |
| 258 | It is possible to print in a custom format by using the `--format` |
| 259 | option, which is able to interpolate different fields using |
| 260 | a `%(fieldname)` notation. For example, if you only care about the |
| 261 | "objectname" and "path" fields, you can execute with a specific |
| 262 | "--format" like |
| 263 | |
| 264 | git ls-files --format='%(objectname) %(path)' |
| 265 | |
| 266 | FIELD NAMES |
| 267 | ----------- |
| 268 | The way each path is shown can be customized by using the |
| 269 | `--format=<format>` option, where the %(fieldname) in the |
| 270 | <format> string for various aspects of the index entry are |
| 271 | interpolated. The following "fieldname" are understood: |
| 272 | |
| 273 | objectmode:: |
| 274 | The mode of the file which is recorded in the index. |
| 275 | objecttype:: |
| 276 | The object type of the file which is recorded in the index. |
| 277 | objectname:: |
| 278 | The name of the file which is recorded in the index. |
| 279 | objectsize[:padded]:: |
| 280 | The object size of the file which is recorded in the index |
| 281 | ("-" if the object is a `commit` or `tree`). |
| 282 | It also supports a padded format of size with "%(objectsize:padded)". |
| 283 | stage:: |
| 284 | The stage of the file which is recorded in the index. |
| 285 | eolinfo:index:: |
| 286 | eolinfo:worktree:: |
| 287 | The <eolinfo> (see the description of the `--eol` option) of |
| 288 | the contents in the index or in the worktree for the path. |
| 289 | eolattr:: |
| 290 | The <eolattr> (see the description of the `--eol` option) |
| 291 | that applies to the path. |
| 292 | path:: |
| 293 | The pathname of the file which is recorded in the index. |
| 294 | |
| 295 | EXCLUDE PATTERNS |
| 296 | ---------------- |
| 297 | |
| 298 | 'git ls-files' can use a list of "exclude patterns" when |
| 299 | traversing the directory tree and finding files to show when the |
| 300 | flags --others or --ignored are specified. linkgit:gitignore[5] |
| 301 | specifies the format of exclude patterns. |
| 302 | |
| 303 | These exclude patterns can be specified from the following places, |
| 304 | in order: |
| 305 | |
| 306 | 1. The command-line flag --exclude=<pattern> specifies a |
| 307 | single pattern. Patterns are ordered in the same order |
| 308 | they appear in the command line. |
| 309 | |
| 310 | 2. The command-line flag --exclude-from=<file> specifies a |
| 311 | file containing a list of patterns. Patterns are ordered |
| 312 | in the same order they appear in the file. |
| 313 | |
| 314 | 3. The command-line flag --exclude-per-directory=<name> specifies |
| 315 | a name of the file in each directory 'git ls-files' |
| 316 | examines, normally `.gitignore`. Files in deeper |
| 317 | directories take precedence. Patterns are ordered in the |
| 318 | same order they appear in the files. |
| 319 | |
| 320 | A pattern specified on the command line with --exclude or read |
| 321 | from the file specified with --exclude-from is relative to the |
| 322 | top of the directory tree. A pattern read from a file specified |
| 323 | by --exclude-per-directory is relative to the directory that the |
| 324 | pattern file appears in. |
| 325 | |
| 326 | Generally, you should be able to use `--exclude-standard` when you |
| 327 | want the exclude rules applied the same way as what Porcelain |
| 328 | commands do. To emulate what `--exclude-standard` specifies, you |
| 329 | can give `--exclude-per-directory=.gitignore`, and then specify: |
| 330 | |
| 331 | 1. The file specified by the `core.excludesfile` configuration |
| 332 | variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file. |
| 333 | |
| 334 | 2. The `$GIT_COMMON_DIR/info/exclude` file. |
| 335 | |
| 336 | via the `--exclude-from=` option. |
| 337 | |
| 338 | SEE ALSO |
| 339 | -------- |
| 340 | linkgit:git-read-tree[1], linkgit:gitignore[5] |
| 341 | |
| 342 | GIT |
| 343 | --- |
| 344 | Part of the linkgit:git[1] suite |