logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-ls-tree.1 (7665B)


  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: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GIT\-LS\-TREE" "1" "2025-03-14" "Git 2\&.49\&.0" "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