NAME
git-ls-files - Show information about files in the index and the working tree
SYNOPSIS
git ls-files\n [-z] [-t] [-v] [-f]
\n
[-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
\n
[-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
\n
[--resolve-undo]
\n
[--directory [--no-empty-directory]] [--eol]
\n
[--deduplicate]
\n
[-x <pattern>|--exclude=<pattern>]
\n
[-X <file>|--exclude-from=<file>]
\n
[--exclude-per-directory=<file>]
\n
[--exclude-standard]
\n
[--error-unmatch] [--with-tree=<tree-ish>]
\n
[--full-name] [--recurse-submodules]
\n
[--abbrev[=<n>]] [--format=<format>] [--] [<file>...]DESCRIPTION
This command merges the file listing in the index with the actual working directory list, and shows different combinations of the two.
Several flags can be used to determine which files are shown, and each file may be printed multiple times if there are multiple entries in the index or if multiple statuses are applicable for the relevant file selection options.
OPTIONS
-c, --cached
-d, --deleted
-m, --modified
-o, --others
-i, --ignored
-s, --stage
--directory
--no-empty-directory
-u, --unmerged
-k, --killed
--resolve-undo
-z
--deduplicate
-x <pattern>, --exclude=<pattern>
-X <file>, --exclude-from=<file>
--exclude-per-directory=<file>
--exclude-standard
--error-unmatch
--with-tree=<tree-ish>
-t
This option provides a reason for showing each filename, in the form of a status tag (which is followed by a space and then the filename). The status tags are all single characters from the following list:
H
S
M
R
C
K
?
U
-v
-f
--full-name
--recurse-submodules
--abbrev[=<n>]
--debug
--eol
"" means the file is not a regular file, it is not in the index or not accessible in the working tree.
<eolattr> is the attribute that is used when checking out or committing, it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
Both the <eolinfo> in the index ("i/<eolinfo>") and in the working tree ("w/<eolinfo>") are shown for regular files, followed by the ("attr/<eolattr>").
--sparse
--format=<format>
--
<file>
OUTPUT
git ls-files just outputs the filenames unless --stage is specified in which case it outputs:
[<tag> ]<mode> <object> <stage> <file>git ls-files --eol will show i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>
git ls-files --unmerged and git ls-files --stage can be used to examine detailed information on unmerged paths.
For an unmerged path, instead of recording a single mode/SHA-1 pair, the index records up to three such pairs; one from tree O in stage 1, A in stage 2, and B in stage 3. This information can be used by the user (or the porcelain) to see what should eventually be recorded at the path. (see git-read-tree(1) for more information on state)
Without the -z option, pathnames with "unusual" characters are quoted as explained for the configuration variable core.quotePath (see git-config(1)). Using -z the filename is output verbatim and the line is terminated by a NUL byte.
It is possible to print in a custom format by using the --format option, which is able to interpolate different fields using a %(fieldname) notation. For example, if you only care about the "objectname" and "path" fields, you can execute with a specific "--format" like
git ls-files --format='%(objectname) %(path)'FIELD NAMES
The way each path is shown can be customized by using the --format=<format> option, where the %(fieldname) in the <format> string for various aspects of the index entry are interpolated. The following "fieldname" are understood:
objectmode
objecttype
objectname
objectsize[:padded]
stage
eolinfo:index, eolinfo:worktree
eolattr
path
EXCLUDE PATTERNS
git ls-files can use a list of "exclude patterns" when traversing the directory tree and finding files to show when the flags --others or --ignored are specified. gitignore(5) specifies the format of exclude patterns.
These exclude patterns can be specified from the following places, in order:
A pattern specified on the command line with --exclude or read from the file specified with --exclude-from is relative to the top of the directory tree. A pattern read from a file specified by --exclude-per-directory is relative to the directory that the pattern file appears in.
Generally, you should be able to use --exclude-standard when you want the exclude rules applied the same way as what Porcelain commands do. To emulate what --exclude-standard specifies, you can give --exclude-per-directory=.gitignore, and then specify:
via the --exclude-from= option.
SEE ALSO
git-read-tree(1), gitignore(5)
GIT
Part of the git(1) suite