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