git-ls-tree.1 (7665B)
- '\" t
- .\" Title: git-ls-tree
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-LS\-TREE" "1" "2025-03-14" "Git 2\&.49\&.0" "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
- .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\fR
- \fBls\-tree\fR
- \fB\-r\fR
- \fBHEAD:sub\fR
- \fBdir\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=\fR\*(Aq%(\fBobjectname\fR)\*(Aq, 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 %(\fBfieldname\fR) from the result being shown\&. It also interpolates %% to %, and %xNN where
- \fBNN\fR
- are hex digits interpolates to character with hex code
- \fBNN\fR; for example %x00 interpolates to \e0 (NUL), %x09 to \et (TAB) and %x0a to \en (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\fR \fB\-\-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 %(\fBfieldname\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