<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article lang="en" id="git-ls-files(1)">
<articleinfo>
    <title>git-ls-files(1)</title>
        <indexterm>
                <primary>git-ls-files(1)</primary>
        </indexterm>
</articleinfo>
<simplesect id="_name">
<title>NAME</title>
<simpara>git-ls-files - Show information about files in the index and the working tree</simpara>
</simplesect>
<simplesect id="_synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git ls-files</emphasis> [-z] [-t] [-v]
                (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
                (-[c|d|o|i|s|u|k|m])*
                [-x &lt;pattern&gt;|--exclude=&lt;pattern&gt;]
                [-X &lt;file&gt;|--exclude-from=&lt;file&gt;]
                [--exclude-per-directory=&lt;file&gt;]
                [--exclude-standard]
                [--error-unmatch] [--with-tree=&lt;tree-ish&gt;]
                [--full-name] [--abbrev] [--] [&lt;file&gt;]\*</literallayout>
</blockquote>
</simplesect>
<simplesect id="_description">
<title>DESCRIPTION</title>
<simpara>This merges the file listing in the directory cache index with the
actual working directory list, and shows different combinations of the
two.</simpara>
<simpara>One or more of the options below may be used to determine the files
shown:</simpara>
</simplesect>
<simplesect id="_options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
-c
</term>
<term>
--cached
</term>
<listitem>
<simpara>
        Show cached files in the output (default)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d
</term>
<term>
--deleted
</term>
<listitem>
<simpara>
        Show deleted files in the output
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-m
</term>
<term>
--modified
</term>
<listitem>
<simpara>
        Show modified files in the output
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-o
</term>
<term>
--others
</term>
<listitem>
<simpara>
        Show other files in the output
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-i
</term>
<term>
--ignored
</term>
<listitem>
<simpara>
        Show ignored files in the output.
        Note that this also reverses any exclude list present.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-s
</term>
<term>
--stage
</term>
<listitem>
<simpara>
        Show staged contents' object name, mode bits and stage number in the output.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--directory
</term>
<listitem>
<simpara>
        If a whole directory is classified as "other", show just its
        name (with a trailing slash) and not its whole contents.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-empty-directory
</term>
<listitem>
<simpara>
        Do not list empty directories. Has no effect without --directory.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-u
</term>
<term>
--unmerged
</term>
<listitem>
<simpara>
        Show unmerged files in the output (forces --stage)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-k
</term>
<term>
--killed
</term>
<listitem>
<simpara>
        Show files on the filesystem that need to be removed due
        to file/directory conflicts for checkout-index to
        succeed.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-z
</term>
<listitem>
<simpara>
        \0 line termination on output.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-x &lt;pattern&gt;
</term>
<term>
--exclude=&lt;pattern&gt;
</term>
<listitem>
<simpara>
        Skips files matching pattern.
        Note that pattern is a shell wildcard pattern.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-X &lt;file&gt;
</term>
<term>
--exclude-from=&lt;file&gt;
</term>
<listitem>
<simpara>
        exclude patterns are read from &lt;file&gt;; 1 per line.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--exclude-per-directory=&lt;file&gt;
</term>
<listitem>
<simpara>
        read additional exclude patterns that apply only to the
        directory and its subdirectories in &lt;file&gt;.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--exclude-standard
</term>
<listitem>
<simpara>
        Add the standard git exclusions: .git/info/exclude, .gitignore
        in each directory, and the user&#8217;s global exclusion file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--error-unmatch
</term>
<listitem>
<simpara>
        If any &lt;file&gt; does not appear in the index, treat this as an
        error (return 1).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--with-tree=&lt;tree-ish&gt;
</term>
<listitem>
<simpara>
        When using --error-unmatch to expand the user supplied
        &lt;file&gt; (i.e. path pattern) arguments to paths, pretend
        that paths which were removed in the index since the
        named &lt;tree-ish&gt; are still present.  Using this option
        with <literal>-s</literal> or <literal>-u</literal> options does not make any sense.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-t
</term>
<listitem>
<simpara>
        Identify the file status with the following tags (followed by
        a space) at the start of each line:
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
H
</term>
<listitem>
<simpara>
cached
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
M
</term>
<listitem>
<simpara>
unmerged
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
R
</term>
<listitem>
<simpara>
removed/deleted
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
C
</term>
<listitem>
<simpara>
modified/changed
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
K
</term>
<listitem>
<simpara>
to be killed
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
?
</term>
<listitem>
<simpara>
other
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-v
</term>
<listitem>
<simpara>
        Similar to <literal>-t</literal>, but use lowercase letters for files
        that are marked as <emphasis>assume unchanged</emphasis> (see
        <xref linkend="git-update-index(1)"/>).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--full-name
</term>
<listitem>
<simpara>
        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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--abbrev[=&lt;n&gt;]
</term>
<listitem>
<simpara>
        Instead of showing the full 40-byte hexadecimal object
        lines, show only a partial prefix.
        Non default number of digits can be specified with --abbrev=&lt;n&gt;.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--
</term>
<listitem>
<simpara>
        Do not interpret any more arguments as options.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;file&gt;
</term>
<listitem>
<simpara>
        Files to show. If no files are given all files which match the other
        specified criteria are shown.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="_output">
<title>Output</title>
<simpara>show files just outputs the filename unless <emphasis>--stage</emphasis> is specified in
which case it outputs:</simpara>
<literallayout class="monospaced">[&lt;tag&gt; ]&lt;mode&gt; &lt;object&gt; &lt;stage&gt; &lt;file&gt;</literallayout>
<simpara><emphasis>git-ls-files --unmerged</emphasis> and <emphasis>git-ls-files --stage</emphasis> can be used to examine
detailed information on unmerged paths.</simpara>
<simpara>For an unmerged path, instead of recording a single mode/SHA1 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 <xref linkend="git-read-tree(1)"/> for more information on state)</simpara>
<simpara>When <literal>-z</literal> option is not used, TAB, LF, and backslash characters
in pathnames are represented as <literal>\t</literal>, <literal>\n</literal>, and <literal>\\</literal>,
respectively.</simpara>
</simplesect>
<simplesect id="_exclude_patterns">
<title>Exclude Patterns</title>
<simpara><emphasis>git-ls-files</emphasis> 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.  <xref linkend="gitignore(5)"/>
specifies the format of exclude patterns.</simpara>
<simpara>These exclude patterns come from these places, in order:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
The command line flag --exclude=&lt;pattern&gt; specifies a
     single pattern.  Patterns are ordered in the same order
     they appear in the command line.
</simpara>
</listitem>
<listitem>
<simpara>
The command line flag --exclude-from=&lt;file&gt; specifies a
     file containing a list of patterns.  Patterns are ordered
     in the same order they appear in the file.
</simpara>
</listitem>
<listitem>
<simpara>
command line flag --exclude-per-directory=&lt;name&gt; specifies
     a name of the file in each directory <emphasis>git-ls-files</emphasis>
     examines, normally <literal>.gitignore</literal>.  Files in deeper
     directories take precedence.  Patterns are ordered in the
     same order they appear in the files.
</simpara>
</listitem>
</orderedlist>
<simpara>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.</simpara>
</simplesect>
<simplesect id="_see_also">
<title>SEE ALSO</title>
<simpara><xref linkend="git-read-tree(1)"/>, <xref linkend="gitignore(5)"/></simpara>
</simplesect>
<simplesect id="_author">
<title>Author</title>
<simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt;</simpara>
</simplesect>
<simplesect id="_documentation">
<title>Documentation</title>
<simpara>Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>
</simplesect>
<simplesect id="_git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
</simplesect>
</article>
