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