Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git cat-file command

Reference for git cat-file: print the type, size or content of any Git object, test whether an object exists, and read thousands of objects with --batch.

git cat-file is the universal object viewer. Give it the name of any object in the database (a blob, tree, commit or tag) and it prints the object's type (-t), its size in bytes (-s), a human-readable rendering (-p) or its raw content. Names can be full or abbreviated IDs or any revision expression such as HEAD:README.md or v1.0^{tree}.

Besides interactive use, cat-file --batch is the standard way for scripts and tools to read many objects through one process, because starting a new git process per object is slow. Most Git GUIs and server-side tools rely on it.

Terminal
git cat-file -p HEAD
git cat-file -t HEAD:README.md
git cat-file --batch-check --batch-all-objects

Try it

Bash Look at the four object types

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Existence checks and batch mode

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git cat-file (-t | -s | -e | -p) [--allow-unknown-type] <object>
git cat-file <type> <object>
git cat-file (--textconv | --filters) [--path=<path>] <object>
git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
             [--buffer] [--follow-symlinks] [--unordered] [-z] [--filters | --textconv]
Name Description
<object> The object to inspect: an ID, abbreviated ID or revision expression.
-t Print the type: blob, tree, commit or tag.
-s Print the size in bytes of the object's content.
-e Print nothing; exit 0 if the object exists and is valid, non-zero otherwise.
-p Pretty-print by type: blob as is, tree as ls-tree lines, commit and tag as text.
<type> <object> Print the raw content. The type must match the object, or the type the name peels to (a tag name with commit gives its commit).
--textconv, --filters Show a blob after applying the diff textconv or the checkout filters (--path names the file whose attributes apply).
--batch[=<format>] Read object names from standard input, one per line; print a header line and then the content for each.
--batch-check[=<format>] Same, but print only the header line.
--batch-command Read commands contents <object>, info <object> and flush for interactive use.
--batch-all-objects Instead of reading names, iterate over every object in the repository (loose and packed).
--buffer Buffer output; flush only at the end (faster for scripts).
--follow-symlinks In batch mode, resolve symbolic links inside the repository.
--unordered With --batch-all-objects, skip sorting and use storage order.
-z Input is NUL-separated instead of newline-separated.
--allow-unknown-type Accept objects of an unknown type (for debugging).

Batch format atoms: %(objectname), %(objecttype), %(objectsize), %(objectsize:disk), %(deltabase) and %(rest) (the text after the object name on the input line, echoed back). The default header is <id> <type> <size>. If a name is not found, the batch output prints <name> missing.

Errors: fatal: Not a valid object name <x>; fatal: git cat-file: could not get object info for a corrupt or absent object; a wrong <type> gives fatal: git cat-file <name>: bad file.

Usage notes

  • -p versus raw. For a tree, -p prints readable lines (100644 blob <id> name), while cat-file tree <id> writes the raw binary tree, which contains NUL bytes. Use ls-tree for programmatic reading.
  • Peeling. git cat-file -t v1 says tag for an annotated tag, but git cat-file -p v1^{commit} shows the commit behind it.
  • Blob content is exact. git cat-file blob HEAD:file reproduces the committed bytes, not the line endings your working tree shows after checkout conversion. Use --filters to see the converted form.
  • Performance. --batch over a pipe is the fast way to read many objects; one process handles hundreds of thousands per second. Use %(objectsize:disk) to find the biggest packed objects. See git verify-pack.
  • Missing objects in a partial clone. Reading a blob that was left out of a --filter=blob:none clone triggers a fetch from the promisor remote.
  • Replace refs. cat-file honours refs/replace/; set GIT_NO_REPLACE_OBJECTS=1 to see the original object. See git replace.
  • Mailmap. --mailmap (with -p or batch) rewrites author and committer lines through .mailmap.