| '\" 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: 05/06/2022 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.36.1.19.ge8005e4871 |
| .\" Language: English |
| .\" |
| .TH "GIT\-LS\-TREE" "1" "05/06/2022" "Git 2\&.36\&.1\&.19\&.ge8005e4" "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%xx\fR |
| where |
| \fBxx\fR |
| are hex digits interpolates to character with hex code |
| \fBxx\fR; for example |
| \fB%00\fR |
| interpolates to |
| \fB\e0\fR |
| (NUL), |
| \fB%09\fR |
| to |
| \fB\et\fR |
| (TAB) and |
| \fB%0a\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 outputing 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 |