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