man1/git-ls-tree.1

   1 '\" t
   2 .\"     Title: git-ls-tree
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-12-10
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.1.440.gcaacdb5dfd
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-LS\-TREE" "1" "2024-12-10" "Git 2\&.47\&.1\&.440\&.gcaacdb" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-ls-tree \- List the contents of a tree object
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit ls\-tree\fR [\-d] [\-r] [\-t] [\-l] [\-z]
  36             [\-\-name\-only] [\-\-name\-status] [\-\-object\-only] [\-\-full\-name] [\-\-full\-tree] [\-\-abbrev[=<n>]] [\-\-format=<format>]
  37             <tree\-ish> [<path>\&...\:]
  38 .fi
  39 .SH "DESCRIPTION"
  40 .sp
  41 Lists the contents of a given tree object, like what "/bin/ls \-a" does in the current working directory\&. Note that:
  42 .sp
  43 .RS 4
  44 .ie n \{\
  45 \h'-04'\(bu\h'+03'\c
  46 .\}
  47 .el \{\
  48 .sp -1
  49 .IP \(bu 2.3
  50 .\}
  51 the behaviour is slightly different from that of "/bin/ls" in that the
  52 \fI<path>\fR
  53 denotes just a list of patterns to match, e\&.g\&. so specifying directory name (without
  54 \fB\-r\fR) will behave differently, and order of the arguments does not matter\&.
  55 .RE
  56 .sp
  57 .RS 4
  58 .ie n \{\
  59 \h'-04'\(bu\h'+03'\c
  60 .\}
  61 .el \{\
  62 .sp -1
  63 .IP \(bu 2.3
  64 .\}
  65 the behaviour is similar to that of "/bin/ls" in that the
  66 \fI<path>\fR
  67 is taken as relative to the current working directory\&. E\&.g\&. when you are in a directory
  68 \fIsub\fR
  69 that has a directory
  70 \fIdir\fR, you can run
  71 \fIgit ls\-tree \-r HEAD dir\fR
  72 to list the contents of the tree (that is
  73 \fBsub/dir\fR
  74 in
  75 \fBHEAD\fR)\&. You don\(cqt want to give a tree that is not at the root level (e\&.g\&.
  76 \fBgit\fR
  77 \fBls\-tree\fR
  78 \fB\-r\fR
  79 \fBHEAD:sub\fR
  80 \fBdir\fR) in this case, as that would result in asking for
  81 \fBsub/sub/dir\fR
  82 in the
  83 \fBHEAD\fR
  84 commit\&. However, the current working directory can be ignored by passing \-\-full\-tree option\&.
  85 .RE
  86 .SH "OPTIONS"
  87 .PP
  88 <tree\-ish>
  89 .RS 4
  90 Id of a tree\-ish\&.
  91 .RE
  92 .PP
  93 \-d
  94 .RS 4
  95 Show only the named tree entry itself, not its children\&.
  96 .RE
  97 .PP
  98 \-r
  99 .RS 4
 100 Recurse into sub\-trees\&.
 101 .RE
 102 .PP
 103 \-t
 104 .RS 4
 105 Show tree entries even when going to recurse them\&. Has no effect if
 106 \fB\-r\fR
 107 was not passed\&.
 108 \fB\-d\fR
 109 implies
 110 \fB\-t\fR\&.
 111 .RE
 112 .PP
 113 \-l, \-\-long
 114 .RS 4
 115 Show object size of blob (file) entries\&.
 116 .RE
 117 .PP
 118 \-z
 119 .RS 4
 120 \e0 line termination on output and do not quote filenames\&. See OUTPUT FORMAT below for more information\&.
 121 .RE
 122 .PP
 123 \-\-name\-only, \-\-name\-status
 124 .RS 4
 125 List only filenames (instead of the "long" output), one per line\&. Cannot be combined with
 126 \fB\-\-object\-only\fR\&.
 127 .RE
 128 .PP
 129 \-\-object\-only
 130 .RS 4
 131 List only names of the objects, one per line\&. Cannot be combined with
 132 \fB\-\-name\-only\fR
 133 or
 134 \fB\-\-name\-status\fR\&. This is equivalent to specifying
 135 \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\&.
 136 .RE
 137 .PP
 138 \-\-abbrev[=<n>]
 139 .RS 4
 140 Instead of showing the full 40\-byte hexadecimal object lines, show the shortest prefix that is at least
 141 \fI<n>\fR
 142 hexdigits long that uniquely refers the object\&. Non default number of digits can be specified with \-\-abbrev=<n>\&.
 143 .RE
 144 .PP
 145 \-\-full\-name
 146 .RS 4
 147 Instead of showing the path names relative to the current working directory, show the full path names\&.
 148 .RE
 149 .PP
 150 \-\-full\-tree
 151 .RS 4
 152 Do not limit the listing to the current working directory\&. Implies \-\-full\-name\&.
 153 .RE
 154 .PP
 155 \-\-format=<format>
 156 .RS 4
 157 A string that interpolates %(\fBfieldname\fR) from the result being shown\&. It also interpolates %% to %, and %xNN where
 158 \fBNN\fR
 159 are hex digits interpolates to character with hex code
 160 \fBNN\fR; for example %x00 interpolates to \e0 (NUL), %x09 to \et (TAB) and %x0a to \en (LF)\&. When specified,
 161 \fB\-\-format\fR
 162 cannot be combined with other format\-altering options, including
 163 \fB\-\-long\fR,
 164 \fB\-\-name\-only\fR
 165 and
 166 \fB\-\-object\-only\fR\&.
 167 .RE
 168 .PP
 169 [<path>\&...\:]
 170 .RS 4
 171 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\&.
 172 .RE
 173 .SH "OUTPUT FORMAT"
 174 .sp
 175 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)\&.
 176 .sp
 177 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\&.
 178 .sp
 179 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:
 180 .sp
 181 .if n \{\
 182 .RS 4
 183 .\}
 184 .nf
 185 %(objectmode) %(objecttype) %(objectname)%x09%(path)
 186 .fi
 187 .if n \{\
 188 .RE
 189 .\}
 190 .sp
 191 This output format is compatible with what \fB\-\-index\-info\fR \fB\-\-stdin\fR of \fIgit update\-index\fR expects\&.
 192 .sp
 193 When the \fB\-l\fR option is used, format changes to
 194 .sp
 195 .if n \{\
 196 .RS 4
 197 .\}
 198 .nf
 199 %(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path)
 200 .fi
 201 .if n \{\
 202 .RE
 203 .\}
 204 .sp
 205 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\&.
 206 .sp
 207 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\&.
 208 .sp
 209 Customized format:
 210 .sp
 211 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
 212 .sp
 213 .if n \{\
 214 .RS 4
 215 .\}
 216 .nf
 217 git ls\-tree \-\-format=\*(Aq%(objectname) %(path)\*(Aq <tree\-ish>
 218 .fi
 219 .if n \{\
 220 .RE
 221 .\}
 222 .SH "FIELD NAMES"
 223 .sp
 224 Various values from structured fields can be used to interpolate into the resulting output\&. For each outputting line, the following names can be used:
 225 .PP
 226 objectmode
 227 .RS 4
 228 The mode of the object\&.
 229 .RE
 230 .PP
 231 objecttype
 232 .RS 4
 233 The type of the object (\fBcommit\fR,
 234 \fBblob\fR
 235 or
 236 \fBtree\fR)\&.
 237 .RE
 238 .PP
 239 objectname
 240 .RS 4
 241 The name of the object\&.
 242 .RE
 243 .PP
 244 objectsize[:padded]
 245 .RS 4
 246 The size of a
 247 \fBblob\fR
 248 object ("\-" if it\(cqs a
 249 \fBcommit\fR
 250 or
 251 \fBtree\fR)\&. It also supports a padded format of size with "%(objectsize:padded)"\&.
 252 .RE
 253 .PP
 254 path
 255 .RS 4
 256 The pathname of the object\&.
 257 .RE
 258 .SH "GIT"
 259 .sp
 260 Part of the \fBgit\fR(1) suite