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 and output is NUL-delimited instead of
 249         newline-delimited.
 250
 251 -z::
 252         Only meaningful with `--batch`, `--batch-check`, or
 253         `--batch-command`; input is NUL-delimited instead of
 254         newline-delimited. This option is deprecated in favor of
 255         `-Z` as the output can otherwise be ambiguous.
 256
 257
 258 OUTPUT
 259 ------
 260 If `-t` is specified, one of the `<type>`.
 261
 262 If `-s` is specified, the size of the `<object>` in bytes.
 263
 264 If `-e` is specified, no output, unless the `<object>` is malformed.
 265
 266 If `-p` is specified, the contents of `<object>` are pretty-printed.
 267
 268 If `<type>` is specified, the raw (though uncompressed) contents of the `<object>`
 269 will be returned.
 270
 271 BATCH OUTPUT
 272 ------------
 273
 274 If `--batch` or `--batch-check` is given, `cat-file` will read objects
 275 from stdin, one per line, and print information about them. By default,
 276 the whole line is considered as an object, as if it were fed to
 277 linkgit:git-rev-parse[1].
 278
 279 When `--batch-command` is given, `cat-file` will read commands from stdin,
 280 one per line, and print information based on the command given. With
 281 `--batch-command`, the `info` command followed by an object will print
 282 information about the object the same way `--batch-check` would, and the
 283 `contents` command followed by an object prints contents in the same way
 284 `--batch` would.
 285
 286 You can specify the information shown for each object by using a custom
 287 `<format>`. The `<format>` is copied literally to stdout for each
 288 object, with placeholders of the form `%(atom)` expanded, followed by a
 289 newline. The available atoms are:
 290
 291 `objectname`::
 292         The full hex representation of the object name.
 293
 294 `objecttype`::
 295         The type of the object (the same as `cat-file -t` reports).
 296
 297 `objectsize`::
 298         The size, in bytes, of the object (the same as `cat-file -s`
 299         reports).
 300
 301 `objectsize:disk`::
 302         The size, in bytes, that the object takes up on disk. See the
 303         note about on-disk sizes in the `CAVEATS` section below.
 304
 305 `deltabase`::
 306         If the object is stored as a delta on-disk, this expands to the
 307         full hex representation of the delta base object name.
 308         Otherwise, expands to the null OID (all zeroes). See `CAVEATS`
 309         below.
 310
 311 `rest`::
 312         If this atom is used in the output string, input lines are split
 313         at the first whitespace boundary. All characters before that
 314         whitespace are considered to be the object name; characters
 315         after that first run of whitespace (i.e., the "rest" of the
 316         line) are output in place of the `%(rest)` atom.
 317
 318 If no format is specified, the default format is `%(objectname)
 319 %(objecttype) %(objectsize)`.
 320
 321 If `--batch` is specified, or if `--batch-command` is used with the `contents`
 322 command, the object information is followed by the object contents (consisting
 323 of `%(objectsize)` bytes), followed by a newline.
 324
 325 For example, `--batch` without a custom format would produce:
 326
 327 ------------
 328 <oid> SP <type> SP <size> LF
 329 <contents> LF
 330 ------------
 331
 332 Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
 333
 334 ------------
 335 <oid> SP <type> LF
 336 ------------
 337
 338 If a name is specified on stdin that cannot be resolved to an object in
 339 the repository, then `cat-file` will ignore any custom format and print:
 340
 341 ------------
 342 <object> SP missing LF
 343 ------------
 344
 345 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:
 346
 347 ------------
 348 <object> SP ambiguous LF
 349 ------------
 350
 351 If `--follow-symlinks` is used, and a symlink in the repository points
 352 outside the repository, then `cat-file` will ignore any custom format
 353 and print:
 354
 355 ------------
 356 symlink SP <size> LF
 357 <symlink> LF
 358 ------------
 359
 360 The symlink will either be absolute (beginning with a `/`), or relative
 361 to the tree root.  For instance, if dir/link points to `../../foo`, then
 362 `<symlink>` will be `../foo`.  `<size>` is the size of the symlink in bytes.
 363
 364 If `--follow-symlinks` is used, the following error messages will be
 365 displayed:
 366
 367 ------------
 368 <object> SP missing LF
 369 ------------
 370 is printed when the initial symlink requested does not exist.
 371
 372 ------------
 373 dangling SP <size> LF
 374 <object> LF
 375 ------------
 376 is printed when the initial symlink exists, but something that
 377 it (transitive-of) points to does not.
 378
 379 ------------
 380 loop SP <size> LF
 381 <object> LF
 382 ------------
 383 is printed for symlink loops (or any symlinks that
 384 require more than 40 link resolutions to resolve).
 385
 386 ------------
 387 notdir SP <size> LF
 388 <object> LF
 389 ------------
 390 is printed when, during symlink resolution, a file is used as a
 391 directory name.
 392
 393 Alternatively, when `-Z` is passed, the line feeds in any of the above examples
 394 are replaced with NUL terminators. This ensures that output will be parsable if
 395 the output itself would contain a linefeed and is thus recommended for
 396 scripting purposes.
 397
 398 CAVEATS
 399 -------
 400
 401 Note that the sizes of objects on disk are reported accurately, but care
 402 should be taken in drawing conclusions about which refs or objects are
 403 responsible for disk usage. The size of a packed non-delta object may be
 404 much larger than the size of objects which delta against it, but the
 405 choice of which object is the base and which is the delta is arbitrary
 406 and is subject to change during a repack.
 407
 408 Note also that multiple copies of an object may be present in the object
 409 database; in this case, it is undefined which copy's size or delta base
 410 will be reported.
 411
 412 GIT
 413 ---
 414 Part of the linkgit:git[1] suite