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