git-cat-file
Display Git object content
TLDR
Get the [s]ize of the HEAD commit in bytes
Get the [t]ype (blob, tree, commit, tag) of a given Git object
Pretty-[p]rint the contents of a given Git object based on its type
SYNOPSIS
git cat-file (-t | -s | -e | -p |
git cat-file (--batch | --batch-check[=
git cat-file (--filters | --textconv) <object>
git cat-file --path=<path> <tree-ish>
PARAMETERS
-t
Instead of the content, show the object’s type (e.g., blob, tree, commit, tag).
-s
Instead of the content, show the object’s size in bytes.
-e
Exit with a zero status if the object exists and is a valid Git object. Otherwise, exit with non-zero status.
-p
Pretty-print the contents of the object. For commits and tags, this includes parsed headers and formatted messages. For trees, it lists contents like git ls-tree. For blobs, it prints the raw content.
Specify the expected object type. If the object is not of this type, git cat-file will exit with an error. Valid types are blob, tree, commit, and tag.
The name of the object to show. This can be a SHA-1 hash, a branch name, a tag name, or any other object name understood by Git (e.g., HEAD, HEAD~1).
--path=
Used with a tree-ish object (e.g., a commit or tree hash), it extracts the content of the specified path from that tree. This is useful for retrieving specific file versions without checking out the whole tree.
--batch
Enable batch mode. Object names are read from standard input, and for each name, the object’s type, size, and content are printed to standard output.
--batch-check[=
Similar to --batch, but only the type and size information (and optionally other metadata specified by format) are printed, not the content. This is faster for just checking object metadata.
--buffer
In batch mode, enable buffering of output for potentially better performance. Only applies to --batch and --batch-check.
--unordered
In batch mode, allows input object names to be unordered. This can be slower as it requires a separate object lookup for each input line, rather than potentially reading contiguous parts of the packfile.
--format=
Specify the output format for --batch-check. Placeholder sequences (e.g., %(objectname), %(objecttype), %(objectsize)) can be used to define the output string.
--filters
When used with a blob object and a --path, apply all relevant filters (e.g., textconv, smudge, clean filters) before displaying its content.
--textconv
Similar to --filters, but specifically applies only the text conversion filter (if configured) before displaying the blob's content.
--no-textconv
Disable text conversion for --path or --filters. Useful when raw content is desired even if textconv is configured.
--no-filters
Disable all filters for --path. Useful when raw content is desired even if filters are configured.
DESCRIPTION
git cat-file is a low-level "plumbing" command in Git, designed to provide information about the objects stored in the repository's object database. It allows users and scripts to inspect the type, size, or raw content of various Git objects such as blobs (file contents), trees (directory structures), commits (snapshots of the repository at a specific time), and tags (references to specific commits or other objects).
This command is crucial for understanding Git's internal mechanics and is frequently used by higher-level "porcelain" commands or custom scripts that need direct access to Git's object model. It can output the object's type, its byte size, or its actual content to standard output. For multiple object lookups, its batch modes offer significant performance advantages.
CAVEATS
git cat-file is a low-level "plumbing" command, meaning it's primarily intended for scripting and internal Git operations rather than direct daily use by end-users.
When retrieving content of blob objects, the output can be binary data, which might not be readable in a standard terminal.
The --path option retrieves content from a tree object directly without checking out the file, but it doesn't apply any working tree attributes or filters by default unless --filters or --textconv are explicitly used.
For performance, batch modes (--batch, --batch-check) are highly recommended when looking up multiple objects, as they significantly reduce the overhead compared to invoking git cat-file repeatedly for each object.
PLUMBING VS. PORCELAIN
git cat-file exemplifies a 'plumbing' command, which operates at a low level directly on Git's internal data structures (the object database). In contrast, 'porcelain' commands (like git commit or git branch) provide a user-friendly interface for common operations, often utilizing multiple plumbing commands internally.
GIT OBJECT MODEL
This command directly interacts with Git's fundamental object types: blobs (raw file data), trees (directory listings that map names to blobs or other trees), commits (snapshots of the repository, including author, committer, message, and parent commits), and tags (references to specific commits or objects, often annotated with messages and signatures).
HISTORY
git cat-file has been a core component of Git since its inception, dating back to the very early versions (e.g., 0.99.x released in 2005). Its fundamental purpose of directly inspecting the Git object database has remained unchanged. Over time, features like the --path option for extracting specific file contents from trees, and particularly the efficient --batch and --batch-check modes, were added to enhance its utility for plumbing scripts requiring high-performance access to multiple objects. It continues to be a crucial tool for understanding and building upon Git's internal object model.
SEE ALSO
git-hash-object(1), git-rev-parse(1), git-ls-tree(1), git-show(1), git-update-index(1)
