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