<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">

<sect2 lang="en" id="git-ls-tree(1)">
    <title>git-ls-tree(1)</title>
    <date>2024-07-02</date>
<revhistory><revision><date>2024-07-02</date></revision></revhistory>
<indexterm>
<primary>git-ls-tree(1)</primary>
</indexterm>
<simplesect id="git-ls-tree(1)__name">
<title>NAME</title>
<simpara>git-ls-tree - List the contents of a tree object</simpara>
</simplesect>
<simplesect id="git-ls-tree(1)__synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git ls-tree</emphasis> [-d] [-r] [-t] [-l] [-z]
            [--name-only] [--name-status] [--object-only] [--full-name] [--full-tree] [--abbrev[=&lt;n&gt;]] [--format=&lt;format&gt;]
            &lt;tree-ish&gt; [&lt;path&gt;&#8230;]</literallayout>
</blockquote>
</simplesect>
<simplesect id="git-ls-tree(1)__description">
<title>DESCRIPTION</title>
<simpara>Lists the contents of a given tree object, like what "/bin/ls -a" does
in the current working directory.  Note that:</simpara>
<itemizedlist>
<listitem>
<simpara>
the behaviour is slightly different from that of "/bin/ls" in that the
   <emphasis>&lt;path&gt;</emphasis> denotes just a list of patterns to match, e.g. so specifying
   directory name (without <emphasis>-r</emphasis>) will behave differently, and order of the
   arguments does not matter.
</simpara>
</listitem>
<listitem>
<simpara>
the behaviour is similar to that of "/bin/ls" in that the <emphasis>&lt;path&gt;</emphasis> is
   taken as relative to the current working directory.  E.g. when you are
   in a directory <emphasis>sub</emphasis> that has a directory <emphasis>dir</emphasis>, you can run <emphasis>git
   ls-tree -r HEAD dir</emphasis> to list the contents of the tree (that is
   <emphasis>sub/dir</emphasis> in <emphasis>HEAD</emphasis>).  You don't want to give a tree that is not at the
   root level (e.g. <emphasis>git ls-tree -r HEAD:sub dir</emphasis>) in this case, as that
   would result in asking for <emphasis>sub/sub/dir</emphasis> in the <emphasis>HEAD</emphasis> commit.
   However, the current working directory can be ignored by passing
   --full-tree option.
</simpara>
</listitem>
</itemizedlist>
</simplesect>
<simplesect id="git-ls-tree(1)__options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
&lt;tree-ish&gt;
</term>
<listitem>
<simpara>
        Id of a tree-ish.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d
</term>
<listitem>
<simpara>
        Show only the named tree entry itself, not its children.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-r
</term>
<listitem>
<simpara>
        Recurse into sub-trees.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-t
</term>
<listitem>
<simpara>
        Show tree entries even when going to recurse them. Has no effect
        if <emphasis>-r</emphasis> was not passed. <emphasis>-d</emphasis> implies <emphasis>-t</emphasis>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-l
</term>
<term>
--long
</term>
<listitem>
<simpara>
        Show object size of blob (file) entries.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-z
</term>
<listitem>
<simpara>
        \0 line termination on output and do not quote filenames.
        See OUTPUT FORMAT below for more information.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--name-only
</term>
<term>
--name-status
</term>
<listitem>
<simpara>
        List only filenames (instead of the "long" output), one per line.
        Cannot be combined with <emphasis>--object-only</emphasis>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--object-only
</term>
<listitem>
<simpara>
        List only names of the objects, one per line. Cannot be combined
        with <emphasis>--name-only</emphasis> or <emphasis>--name-status</emphasis>.
        This is equivalent to specifying <emphasis>--format='%(objectname)'</emphasis>, but
        for both this option and that exact format the command takes a
        hand-optimized codepath instead of going through the generic
        formatting mechanism.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--abbrev[=&lt;n&gt;]
</term>
<listitem>
<simpara>
        Instead of showing the full 40-byte hexadecimal object
        lines, show the shortest prefix that is at least <emphasis>&lt;n&gt;</emphasis>
        hexdigits long that uniquely refers the object.
        Non default number of digits can be specified with --abbrev=&lt;n&gt;.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--full-name
</term>
<listitem>
<simpara>
        Instead of showing the path names relative to the current working
        directory, show the full path names.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--full-tree
</term>
<listitem>
<simpara>
        Do not limit the listing to the current working directory.
        Implies --full-name.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--format=&lt;format&gt;
</term>
<listitem>
<simpara>
        A string that interpolates <emphasis>%(fieldname)</emphasis> from the result
        being shown. It also interpolates <emphasis>%%</emphasis> to <emphasis>%</emphasis>, and
        <emphasis>%xNN</emphasis> where <emphasis>NN</emphasis> are hex digits interpolates to character
        with hex code <emphasis>NN</emphasis>; for example <emphasis>%x00</emphasis> interpolates to
        <emphasis>\0</emphasis> (NUL), <emphasis>%x09</emphasis> to <emphasis>\t</emphasis> (TAB) and <emphasis>%x0a</emphasis> to <emphasis>\n</emphasis> (LF).
        When specified, <emphasis>--format</emphasis> cannot be combined with other
        format-altering options, including <emphasis>--long</emphasis>, <emphasis>--name-only</emphasis>
        and <emphasis>--object-only</emphasis>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
[&lt;path&gt;&#8230;]
</term>
<listitem>
<simpara>
        When paths are given, show them (note that this isn't really raw
        pathnames, but rather a list of patterns to match).  Otherwise
        implicitly uses the root level of the tree as the sole path argument.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="git-ls-tree(1)__output_format">
<title>Output Format</title>
<simpara>The output format of <emphasis>ls-tree</emphasis> is determined by either the <emphasis>--format</emphasis>
option, or other format-altering options such as <emphasis>--name-only</emphasis> etc.
(see <emphasis>--format</emphasis> above).</simpara>
<simpara>The use of certain <emphasis>--format</emphasis> directives is equivalent to using those
options, but invoking the full formatting machinery can be slower than
using an appropriate formatting option.</simpara>
<simpara>In cases where the <emphasis>--format</emphasis> would exactly map to an existing option
<emphasis>ls-tree</emphasis> will use the appropriate faster path. Thus the default format
is equivalent to:</simpara>
<literallayout class="monospaced">%(objectmode) %(objecttype) %(objectname)%x09%(path)</literallayout>
<simpara>This output format is compatible with what <emphasis>--index-info --stdin</emphasis> of
<emphasis>git update-index</emphasis> expects.</simpara>
<simpara>When the <emphasis>-l</emphasis> option is used, format changes to</simpara>
<literallayout class="monospaced">%(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path)</literallayout>
<simpara>Object size identified by &lt;objectname&gt; is given in bytes, and right-justified
with minimum width of 7 characters.  Object size is given only for blobs
(file) entries; for other entries <emphasis>-</emphasis> character is used in place of size.</simpara>
<simpara>Without the <emphasis>-z</emphasis> option, pathnames with "unusual" characters are
quoted as explained for the configuration variable <emphasis>core.quotePath</emphasis>
(see <xref linkend="git-config(1)" />).  Using <emphasis>-z</emphasis> the filename is output
verbatim and the line is terminated by a NUL byte.</simpara>
<simpara>Customized format:</simpara>
<simpara>It is possible to print in a custom format by using the <emphasis>--format</emphasis> option,
which is able to interpolate different fields using a <emphasis>%(fieldname)</emphasis> notation.
For example, if you only care about the "objectname" and "path" fields, you
can execute with a specific "--format" like</simpara>
<literallayout class="monospaced">git ls-tree --format='%(objectname) %(path)' &lt;tree-ish&gt;</literallayout>
</simplesect>
<simplesect id="git-ls-tree(1)__field_names">
<title>FIELD NAMES</title>
<simpara>Various values from structured fields can be used to interpolate
into the resulting output. For each outputting line, the following
names can be used:</simpara>
<variablelist>
<varlistentry>
<term>
objectmode
</term>
<listitem>
<simpara>
        The mode of the object.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
objecttype
</term>
<listitem>
<simpara>
        The type of the object (<emphasis>commit</emphasis>, <emphasis>blob</emphasis> or <emphasis>tree</emphasis>).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
objectname
</term>
<listitem>
<simpara>
        The name of the object.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
objectsize[:padded]
</term>
<listitem>
<simpara>
        The size of a <emphasis>blob</emphasis> object ("-" if it's a <emphasis>commit</emphasis> or <emphasis>tree</emphasis>).
        It also supports a padded format of size with "%(objectsize:padded)".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
path
</term>
<listitem>
<simpara>
        The pathname of the object.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="git-ls-tree(1)__git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)" /> suite</simpara>
</simplesect>
</sect2>
