Documentation/git-cat-file.txt

   1 git-cat-file(1)
   2 ===============
   3
   4 NAME
   5 ----
   6 git-cat-file - Provide content or type and size information for repository objects
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git cat-file' <type> <object>
  13 'git cat-file' (-e | -p) <object>
  14 'git cat-file' (-t | -s) [--allow-unknown-type] <object>
  15 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]
  16              [--buffer] [--follow-symlinks] [--unordered]
  17              [--textconv | --filters] [-z]
  18 'git cat-file' (--textconv | --filters)
  19              [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
  20
  21 DESCRIPTION
  22 -----------
  23 In its first form, the command provides the content or the type of an object in
  24 the repository. The type is required unless `-t` or `-p` is used to find the
  25 object type, or `-s` is used to find the object size, or `--textconv` or
  26 `--filters` is used (which imply type "blob").
  27
  28 In the second form, a list of objects (separated by linefeeds) is provided on
  29 stdin, and the SHA-1, type, and size of each object is printed on stdout. The
  30 output format can be overridden using the optional `<format>` argument. If
  31 either `--textconv` or `--filters` was specified, the input is expected to
  32 list the object names followed by the path name, separated by a single
  33 whitespace, so that the appropriate drivers can be determined.
  34
  35 OPTIONS
  36 -------
  37 <object>::
  38         The name of the object to show.
  39         For a more complete list of ways to spell object names, see
  40         the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
  41
  42 -t::
  43         Instead of the content, show the object type identified by
  44         `<object>`.
  45
  46 -s::
  47         Instead of the content, show the object size identified by
  48         `<object>`. If used with `--use-mailmap` option, will show
  49         the size of updated object after replacing idents using the
  50         mailmap mechanism.
  51
  52 -e::
  53         Exit with zero status if `<object>` exists and is a valid
  54         object. If `<object>` is of an invalid format exit with non-zero and
  55         emits an error on stderr.
  56
  57 -p::
  58         Pretty-print the contents of `<object>` based on its type.
  59
  60 <type>::
  61         Typically this matches the real type of `<object>` but asking
  62         for a type that can trivially be dereferenced from the given
  63         `<object>` is also permitted.  An example is to ask for a
  64         "tree" with `<object>` being a commit object that contains it,
  65         or to ask for a "blob" with `<object>` being a tag object that
  66         points at it.
  67
  68 --[no-]mailmap::
  69 --[no-]use-mailmap::
  70        Use mailmap file to map author, committer and tagger names
  71        and email addresses to canonical real names and email addresses.
  72        See linkgit:git-shortlog[1].
  73
  74 --textconv::
  75         Show the content as transformed by a textconv filter. In this case,
  76         `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>` in
  77         order to apply the filter to the content recorded in the index at
  78         `<path>`.
  79
  80 --filters::
  81         Show the content as converted by the filters configured in
  82         the current working tree for the given `<path>` (i.e. smudge filters,
  83         end-of-line conversion, etc). In this case, `<object>` has to be of
  84         the form `<tree-ish>:<path>`, or `:<path>`.
  85
  86 --path=<path>::
  87         For use with `--textconv` or `--filters`, to allow specifying an object
  88         name and a path separately, e.g. when it is difficult to figure out
  89         the revision from which the blob came.
  90
  91 --batch::
  92 --batch=<format>::
  93         Print object information and contents for each object provided
  94         on stdin. May not be combined with any other options or arguments
  95         except `--textconv`, `--filters`, or `--use-mailmap`.
  96 +
  97 --
  98         * When used with `--textconv` or `--filters`, the input lines
  99           must specify the path, separated by whitespace. See the section
 100           `BATCH OUTPUT` below for details.
 101
 102         * When used with `--use-mailmap`, for commit and tag objects, the
 103           contents part of the output shows the identities replaced using the
 104           mailmap mechanism, while the information part of the output shows
 105           the size of the object as if it actually recorded the replacement
 106           identities.
 107 --
 108
 109 --batch-check::
 110 --batch-check=<format>::
 111         Print object information for each object provided on stdin. May not be
 112         combined with any other options or arguments except `--textconv`, `--filters`
 113         or `--use-mailmap`.
 114 +
 115 --
 116         * When used with `--textconv` or `--filters`, the input lines must
 117          specify the path, separated by whitespace. See the section
 118          `BATCH OUTPUT` below for details.
 119
 120         * When used with `--use-mailmap`, for commit and tag objects, the
 121           printed object information shows the size of the object as if the
 122           identities recorded in it were replaced by the mailmap mechanism.
 123 --
 124
 125 --batch-command::
 126 --batch-command=<format>::
 127         Enter a command mode that reads commands and arguments from stdin. May
 128         only be combined with `--buffer`, `--textconv`, `--use-mailmap` or
 129         `--filters`.
 130 +
 131 --
 132         * When used with `--textconv` or `--filters`, the input lines must
 133           specify the path, separated by whitespace. See the section
 134           `BATCH OUTPUT` below for details.
 135
 136         * When used with `--use-mailmap`, for commit and tag objects, the
 137           `contents` command shows the identities replaced using the
 138           mailmap mechanism, while the `info` command shows the size
 139           of the object as if it actually recorded the replacement
 140           identities.
 141 --
 142 +
 143 `--batch-command` recognizes the following commands:
 144 +
 145 --
 146 contents <object>::
 147         Print object contents for object reference `<object>`. This corresponds to
 148         the output of `--batch`.
 149
 150 info <object>::
 151         Print object info for object reference `<object>`. This corresponds to the
 152         output of `--batch-check`.
 153
 154 flush::
 155         Used with `--buffer` to execute all preceding commands that were issued
 156         since the beginning or since the last flush was issued. When `--buffer`
 157         is used, no output will come until a `flush` is issued. When `--buffer`
 158         is not used, commands are flushed each time without issuing `flush`.
 159 --
 160 +
 161
 162 --batch-all-objects::
 163         Instead of reading a list of objects on stdin, perform the
 164         requested batch operation on all objects in the repository and
 165         any alternate object stores (not just reachable objects).
 166         Requires `--batch` or `--batch-check` be specified. By default,
 167         the objects are visited in order sorted by their hashes; see
 168         also `--unordered` below. Objects are presented as-is, without
 169         respecting the "replace" mechanism of linkgit:git-replace[1].
 170
 171 --buffer::
 172         Normally batch output is flushed after each object is output, so
 173         that a process can interactively read and write from
 174         `cat-file`. With this option, the output uses normal stdio
 175         buffering; this is much more efficient when invoking
 176         `--batch-check` or `--batch-command` on a large number of objects.
 177
 178 --unordered::
 179         When `--batch-all-objects` is in use, visit objects in an
 180         order which may be more efficient for accessing the object
 181         contents than hash order. The exact details of the order are
 182         unspecified, but if you do not require a specific order, this
 183         should generally result in faster output, especially with
 184         `--batch`.  Note that `cat-file` will still show each object
 185         only once, even if it is stored multiple times in the
 186         repository.
 187
 188 --allow-unknown-type::
 189         Allow `-s` or `-t` to query broken/corrupt objects of unknown type.
 190
 191 --follow-symlinks::
 192         With `--batch` or `--batch-check`, follow symlinks inside the
 193         repository when requesting objects with extended SHA-1
 194         expressions of the form tree-ish:path-in-tree.  Instead of
 195         providing output about the link itself, provide output about
 196         the linked-to object.  If a symlink points outside the
 197         tree-ish (e.g. a link to `/foo` or a root-level link to `../foo`),
 198         the portion of the link which is outside the tree will be
 199         printed.
 200 +
 201 This option does not (currently) work correctly when an object in the
 202 index is specified (e.g. `:link` instead of `HEAD:link`) rather than
 203 one in the tree.
 204 +
 205 This option cannot (currently) be used unless `--batch` or
 206 `--batch-check` is used.
 207 +
 208 For example, consider a git repository containing:
 209 +
 210 --
 211         f: a file containing "hello\n"
 212         link: a symlink to f
 213         dir/link: a symlink to ../f
 214         plink: a symlink to ../f
 215         alink: a symlink to /etc/passwd
 216 --
 217 +
 218 For a regular file `f`, `echo HEAD:f | git cat-file --batch` would print
 219 +
 220 --
 221         ce013625030ba8dba906f756967f9e9ca394464a blob 6
 222 --
 223 +
 224 And `echo HEAD:link | git cat-file --batch --follow-symlinks` would
 225 print the same thing, as would `HEAD:dir/link`, as they both point at
 226 `HEAD:f`.
 227 +
 228 Without `--follow-symlinks`, these would print data about the symlink
 229 itself.  In the case of `HEAD:link`, you would see
 230 +
 231 --
 232         4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1
 233 --
 234 +
 235 Both `plink` and `alink` point outside the tree, so they would
 236 respectively print:
 237 +
 238 --
 239         symlink 4
 240         ../f
 241
 242         symlink 11
 243         /etc/passwd
 244 --
 245
 246 -z::
 247         Only meaningful with `--batch`, `--batch-check`, or
 248         `--batch-command`; input is NUL-delimited instead of
 249         newline-delimited.
 250
 251
 252 OUTPUT
 253 ------
 254 If `-t` is specified, one of the `<type>`.
 255
 256 If `-s` is specified, the size of the `<object>` in bytes.
 257
 258 If `-e` is specified, no output, unless the `<object>` is malformed.
 259
 260 If `-p` is specified, the contents of `<object>` are pretty-printed.
 261
 262 If `<type>` is specified, the raw (though uncompressed) contents of the `<object>`
 263 will be returned.
 264
 265 BATCH OUTPUT
 266 ------------
 267
 268 If `--batch` or `--batch-check` is given, `cat-file` will read objects
 269 from stdin, one per line, and print information about them. By default,
 270 the whole line is considered as an object, as if it were fed to
 271 linkgit:git-rev-parse[1].
 272
 273 When `--batch-command` is given, `cat-file` will read commands from stdin,
 274 one per line, and print information based on the command given. With
 275 `--batch-command`, the `info` command followed by an object will print
 276 information about the object the same way `--batch-check` would, and the
 277 `contents` command followed by an object prints contents in the same way
 278 `--batch` would.
 279
 280 You can specify the information shown for each object by using a custom
 281 `<format>`. The `<format>` is copied literally to stdout for each
 282 object, with placeholders of the form `%(atom)` expanded, followed by a
 283 newline. The available atoms are:
 284
 285 `objectname`::
 286         The full hex representation of the object name.
 287
 288 `objecttype`::
 289         The type of the object (the same as `cat-file -t` reports).
 290
 291 `objectsize`::
 292         The size, in bytes, of the object (the same as `cat-file -s`
 293         reports).
 294
 295 `objectsize:disk`::
 296         The size, in bytes, that the object takes up on disk. See the
 297         note about on-disk sizes in the `CAVEATS` section below.
 298
 299 `deltabase`::
 300         If the object is stored as a delta on-disk, this expands to the
 301         full hex representation of the delta base object name.
 302         Otherwise, expands to the null OID (all zeroes). See `CAVEATS`
 303         below.
 304
 305 `rest`::
 306         If this atom is used in the output string, input lines are split
 307         at the first whitespace boundary. All characters before that
 308         whitespace are considered to be the object name; characters
 309         after that first run of whitespace (i.e., the "rest" of the
 310         line) are output in place of the `%(rest)` atom.
 311
 312 If no format is specified, the default format is `%(objectname)
 313 %(objecttype) %(objectsize)`.
 314
 315 If `--batch` is specified, or if `--batch-command` is used with the `contents`
 316 command, the object information is followed by the object contents (consisting
 317 of `%(objectsize)` bytes), followed by a newline.
 318
 319 For example, `--batch` without a custom format would produce:
 320
 321 ------------
 322 <oid> SP <type> SP <size> LF
 323 <contents> LF
 324 ------------
 325
 326 Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
 327
 328 ------------
 329 <oid> SP <type> LF
 330 ------------
 331
 332 If a name is specified on stdin that cannot be resolved to an object in
 333 the repository, then `cat-file` will ignore any custom format and print:
 334
 335 ------------
 336 <object> SP missing LF
 337 ------------
 338
 339 If a name is specified that might refer to more than one object (an ambiguous short sha), then `cat-file` will ignore any custom format and print:
 340
 341 ------------
 342 <object> SP ambiguous LF
 343 ------------
 344
 345 If `--follow-symlinks` is used, and a symlink in the repository points
 346 outside the repository, then `cat-file` will ignore any custom format
 347 and print:
 348
 349 ------------
 350 symlink SP <size> LF
 351 <symlink> LF
 352 ------------
 353
 354 The symlink will either be absolute (beginning with a `/`), or relative
 355 to the tree root.  For instance, if dir/link points to `../../foo`, then
 356 `<symlink>` will be `../foo`.  `<size>` is the size of the symlink in bytes.
 357
 358 If `--follow-symlinks` is used, the following error messages will be
 359 displayed:
 360
 361 ------------
 362 <object> SP missing LF
 363 ------------
 364 is printed when the initial symlink requested does not exist.
 365
 366 ------------
 367 dangling SP <size> LF
 368 <object> LF
 369 ------------
 370 is printed when the initial symlink exists, but something that
 371 it (transitive-of) points to does not.
 372
 373 ------------
 374 loop SP <size> LF
 375 <object> LF
 376 ------------
 377 is printed for symlink loops (or any symlinks that
 378 require more than 40 link resolutions to resolve).
 379
 380 ------------
 381 notdir SP <size> LF
 382 <object> LF
 383 ------------
 384 is printed when, during symlink resolution, a file is used as a
 385 directory name.
 386
 387 CAVEATS
 388 -------
 389
 390 Note that the sizes of objects on disk are reported accurately, but care
 391 should be taken in drawing conclusions about which refs or objects are
 392 responsible for disk usage. The size of a packed non-delta object may be
 393 much larger than the size of objects which delta against it, but the
 394 choice of which object is the base and which is the delta is arbitrary
 395 and is subject to change during a repack.
 396
 397 Note also that multiple copies of an object may be present in the object
 398 database; in this case, it is undefined which copy's size or delta base
 399 will be reported.
 400
 401 GIT
 402 ---
 403 Part of the linkgit:git[1] suite