path: root/man1/git-ls-tree.1

'\" t
.\"     Title: git-ls-tree
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-19
.\"    Manual: Git Manual
.\"    Source: Git 2.45.0.rc0
.\"  Language: English
.\"
.TH "GIT\-LS\-TREE" "1" "2024\-04\-19" "Git 2\&.45\&.0\&.rc0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-ls-tree \- List the contents of a tree object
.SH "SYNOPSIS"
.sp
.nf
\fIgit ls\-tree\fR [\-d] [\-r] [\-t] [\-l] [\-z]
            [\-\-name\-only] [\-\-name\-status] [\-\-object\-only] [\-\-full\-name] [\-\-full\-tree] [\-\-abbrev[=<n>]] [\-\-format=<format>]
            <tree\-ish> [<path>\&...]
.fi
.sp
.SH "DESCRIPTION"
.sp
Lists the contents of a given tree object, like what "/bin/ls \-a" does in the current working directory\&. Note that:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the behaviour is slightly different from that of "/bin/ls" in that the
\fI<path>\fR
denotes just a list of patterns to match, e\&.g\&. so specifying directory name (without
\fB\-r\fR) will behave differently, and order of the arguments does not matter\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the behaviour is similar to that of "/bin/ls" in that the
\fI<path>\fR
is taken as relative to the current working directory\&. E\&.g\&. when you are in a directory
\fIsub\fR
that has a directory
\fIdir\fR, you can run
\fIgit ls\-tree \-r HEAD dir\fR
to list the contents of the tree (that is
\fBsub/dir\fR
in
\fBHEAD\fR)\&. You don\(cqt want to give a tree that is not at the root level (e\&.g\&.
\fBgit ls\-tree \-r HEAD:sub dir\fR) in this case, as that would result in asking for
\fBsub/sub/dir\fR
in the
\fBHEAD\fR
commit\&. However, the current working directory can be ignored by passing \-\-full\-tree option\&.
.RE
.SH "OPTIONS"
.PP
<tree\-ish>
.RS 4
Id of a tree\-ish\&.
.RE
.PP
\-d
.RS 4
Show only the named tree entry itself, not its children\&.
.RE
.PP
\-r
.RS 4
Recurse into sub\-trees\&.
.RE
.PP
\-t
.RS 4
Show tree entries even when going to recurse them\&. Has no effect if
\fB\-r\fR
was not passed\&.
\fB\-d\fR
implies
\fB\-t\fR\&.
.RE
.PP
\-l, \-\-long
.RS 4
Show object size of blob (file) entries\&.
.RE
.PP
\-z
.RS 4
\e0 line termination on output and do not quote filenames\&. See OUTPUT FORMAT below for more information\&.
.RE
.PP
\-\-name\-only, \-\-name\-status
.RS 4
List only filenames (instead of the "long" output), one per line\&. Cannot be combined with
\fB\-\-object\-only\fR\&.
.RE
.PP
\-\-object\-only
.RS 4
List only names of the objects, one per line\&. Cannot be combined with
\fB\-\-name\-only\fR
or
\fB\-\-name\-status\fR\&. This is equivalent to specifying
\fB\-\-format=\*(Aq%(objectname)\*(Aq\fR, but for both this option and that exact format the command takes a hand\-optimized codepath instead of going through the generic formatting mechanism\&.
.RE
.PP
\-\-abbrev[=<n>]
.RS 4
Instead of showing the full 40\-byte hexadecimal object lines, show the shortest prefix that is at least
\fI<n>\fR
hexdigits long that uniquely refers the object\&. Non default number of digits can be specified with \-\-abbrev=<n>\&.
.RE
.PP
\-\-full\-name
.RS 4
Instead of showing the path names relative to the current working directory, show the full path names\&.
.RE
.PP
\-\-full\-tree
.RS 4
Do not limit the listing to the current working directory\&. Implies \-\-full\-name\&.
.RE
.PP
\-\-format=<format>
.RS 4
A string that interpolates
\fB%(fieldname)\fR
from the result being shown\&. It also interpolates
\fB%%\fR
to
\fB%\fR, and
\fB%xNN\fR
where
\fBNN\fR
are hex digits interpolates to character with hex code
\fBNN\fR; for example
\fB%x00\fR
interpolates to
\fB\e0\fR
(NUL),
\fB%x09\fR
to
\fB\et\fR
(TAB) and
\fB%x0a\fR
to
\fB\en\fR
(LF)\&. When specified,
\fB\-\-format\fR
cannot be combined with other format\-altering options, including
\fB\-\-long\fR,
\fB\-\-name\-only\fR
and
\fB\-\-object\-only\fR\&.
.RE
.PP
[<path>\&...]
.RS 4
When paths are given, show them (note that this isn\(cqt 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\&.
.RE
.SH "OUTPUT FORMAT"
.sp
The output format of \fBls\-tree\fR is determined by either the \fB\-\-format\fR option, or other format\-altering options such as \fB\-\-name\-only\fR etc\&. (see \fB\-\-format\fR above)\&.
.sp
The use of certain \fB\-\-format\fR directives is equivalent to using those options, but invoking the full formatting machinery can be slower than using an appropriate formatting option\&.
.sp
In cases where the \fB\-\-format\fR would exactly map to an existing option \fBls\-tree\fR will use the appropriate faster path\&. Thus the default format is equivalent to:
.sp
.if n \{\
.RS 4
.\}
.nf
%(objectmode) %(objecttype) %(objectname)%x09%(path)
.fi
.if n \{\
.RE
.\}
.sp
This output format is compatible with what \fB\-\-index\-info \-\-stdin\fR of \fIgit update\-index\fR expects\&.
.sp
When the \fB\-l\fR option is used, format changes to
.sp
.if n \{\
.RS 4
.\}
.nf
%(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path)
.fi
.if n \{\
.RE
.\}
.sp
Object size identified by <objectname> 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 \fB\-\fR character is used in place of size\&.
.sp
Without the \fB\-z\fR option, pathnames with "unusual" characters are quoted as explained for the configuration variable \fBcore\&.quotePath\fR (see \fBgit-config\fR(1))\&. Using \fB\-z\fR the filename is output verbatim and the line is terminated by a NUL byte\&.
.sp
Customized format:
.sp
It is possible to print in a custom format by using the \fB\-\-format\fR option, which is able to interpolate different fields using a \fB%(fieldname)\fR notation\&. For example, if you only care about the "objectname" and "path" fields, you can execute with a specific "\-\-format" like
.sp
.if n \{\
.RS 4
.\}
.nf
git ls\-tree \-\-format=\*(Aq%(objectname) %(path)\*(Aq <tree\-ish>
.fi
.if n \{\
.RE
.\}
.SH "FIELD NAMES"
.sp
Various values from structured fields can be used to interpolate into the resulting output\&. For each outputting line, the following names can be used:
.PP
objectmode
.RS 4
The mode of the object\&.
.RE
.PP
objecttype
.RS 4
The type of the object (\fBcommit\fR,
\fBblob\fR
or
\fBtree\fR)\&.
.RE
.PP
objectname
.RS 4
The name of the object\&.
.RE
.PP
objectsize[:padded]
.RS 4
The size of a
\fBblob\fR
object ("\-" if it\(cqs a
\fBcommit\fR
or
\fBtree\fR)\&. It also supports a padded format of size with "%(objectsize:padded)"\&.
.RE
.PP
path
.RS 4
The pathname of the object\&.
.RE
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite