.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "GIT-LS-FILES" 1 "" "" ""
.SH NAME
git-ls-files \- Information about files in the index/working directory
.SH "SYNOPSIS"

.nf
\fIgit\-ls\-files\fR [\-z] [\-t] [\-v]
                (\-\-[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
                (\-[c|d|o|i|s|u|k|m])*
                [\-x <pattern>|\-\-exclude=<pattern>]
                [\-X <file>|\-\-exclude\-from=<file>]
                [\-\-exclude\-per\-directory=<file>]
                [\-\-error\-unmatch]
                [\-\-full\-name] [\-\-] [<file>]*
.fi

.SH "DESCRIPTION"


This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two\&.


One or more of the options below may be used to determine the files shown:

.SH "OPTIONS"

.TP
\-c|\-\-cached
Show cached files in the output (default)

.TP
\-d|\-\-deleted
Show deleted files in the output

.TP
\-m|\-\-modified
Show modified files in the output

.TP
\-o|\-\-others
Show other files in the output

.TP
\-i|\-\-ignored
Show ignored files in the output Note the this also reverses any exclude list present\&.

.TP
\-s|\-\-stage
Show stage files in the output

.TP
\-\-directory
If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents\&.

.TP
\-u|\-\-unmerged
Show unmerged files in the output (forces \-\-stage)

.TP
\-k|\-\-killed
Show files on the filesystem that need to be removed due to file/directory conflicts for checkout\-index to succeed\&.

.TP
\-z
\\0 line termination on output\&.

.TP
\-x|\-\-exclude=<pattern>
Skips files matching pattern\&. Note that pattern is a shell wildcard pattern\&.

.TP
\-X|\-\-exclude\-from=<file>
exclude patterns are read from <file>; 1 per line\&.

.TP
\-\-exclude\-per\-directory=<file>
read additional exclude patterns that apply only to the directory and its subdirectories in <file>\&.

.TP
\-\-error\-unmatch
If any <file> does not appear in the index, treat this as an error (return 1)\&.

.TP
\-t
Identify the file status with the following tags (followed by a space) at the start of each line:
H

cached

M

unmerged

R

removed/deleted

C

modified/changed

K

to be killed

?

other


.TP
\-v
Similar to \-t, but use lowercase letters for files that are marked as \fIalways matching index\fR\&.

.TP
\-\-full\-name
When run from a subdirectory, the command usually outputs paths relative to the current directory\&. This option forces paths to be output relative to the project top directory\&.

.TP
--
Do not interpret any more arguments as options\&.

.TP
<file>
Files to show\&. If no files are given all files which match the other specified criteria are shown\&.

.SH "OUTPUT"


show files just outputs the filename unless \fI\-\-stage\fR is specified in which case it outputs:

.nf
[<tag> ]<mode> <object> <stage> <file>
.fi


"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/SHA1 pair, the dircache 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 for more information on state)


When \-z option is not used, TAB, LF, and backslash characters in pathnames are represented as \\t, \\n, and \\\\, respectively\&.

.SH "EXCLUDE PATTERNS"


\fIgit\-ls\-files\fR 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\&.


These exclude patterns come from these places:

.TP 3
1.
command line flag \-\-exclude=<pattern> specifies a single pattern\&.
.TP
2.
command line flag \-\-exclude\-from=<file> specifies a list of patterns stored in a file\&.
.TP
3.
command line flag \-\-exclude\-per\-directory=<name> specifies a name of the file in each directory \fIgit\-ls\-files\fR examines, and if exists, its contents are used as an additional list of patterns\&.
.LP


An exclude pattern file used by (2) and (3) contains one pattern per line\&. A line that starts with a \fI#\fR can be used as comment for readability\&.


There are three lists of patterns that are in effect at a given time\&. They are built and ordered in the following way:

.TP 3
\(bu
\-\-exclude=<pattern> from the command line; patterns are ordered in the same order as they appear on the command line\&.
.TP
\(bu
lines read from \-\-exclude\-from=<file>; patterns are ordered in the same order as they appear in the file\&.
.TP
\(bu
When \-\-exclude\-per\-directory=<name> is specified, upon entering a directory that has such a file, its contents are appended at the end of the current "list of patterns"\&. They are popped off when leaving the directory\&.
.LP


Each pattern in the pattern list specifies "a match pattern" and optionally the fate; either a file that matches the pattern is considered excluded or included\&. A filename is matched against the patterns in the three lists; the \-\-exclude\-from list is checked first, then the \-\-exclude\-per\-directory list, and then finally the \-\-exclude list\&. The last match determines its fate\&. If there is no match in the three lists, the fate is "included"\&.


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\&.


An exclude pattern is of the following format:

.TP 3
\(bu
an optional prefix \fI!\fR which means that the fate this pattern specifies is "include", not the usual "exclude"; the remainder of the pattern string is interpreted according to the following rules\&.
.TP
\(bu
if it does not contain a slash \fI/\fR, it is a shell glob pattern and used to match against the filename without leading directories (i\&.e\&. the same way as the current implementation)\&.
.TP
\(bu
otherwise, it is a shell glob pattern, suitable for consumption by fnmatch(3) with FNM_PATHNAME flag\&. I\&.e\&. a slash in the pattern must match a slash in the pathname\&. "Documentation/*\&.html" matches "Documentation/git\&.html" but not "ppc/ppc\&.html"\&. As a natural exception, "/*\&.c" matches "cat\-file\&.c" but not "mozilla\-sha1/sha1\&.c"\&.
.LP


An example:

.IP
    $ cat \&.git/ignore
    # ignore objects and archives, anywhere in the tree\&.
    *\&.[oa]
    $ cat Documentation/\&.gitignore
    # ignore generated html files,
    *\&.html
    # except foo\&.html which is maintained by hand
    !foo\&.html
    $ git\-ls\-files \-\-ignored \\
        \-\-exclude='Documentation/*\&.[0\-9]' \\
        \-\-exclude\-from=\&.git/ignore \\
        \-\-exclude\-per\-directory=\&.gitignore
.SH "SEE ALSO"


\fBgit\-read\-tree\fR(1)

.SH "AUTHOR"


Written by Linus Torvalds <torvalds@osdl\&.org>

.SH "DOCUMENTATION"


Documentation by David Greaves, Junio C Hamano and the git\-list <git@vger\&.kernel\&.org>\&.

.SH "GIT"


Part of the \fBgit\fR(7) suite