git cat-file: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

git cat-file is the plumbing that reveals the type, size, and content of any Git object.

cat-file is the low-level lens on the object store - useful for scripts that verify objects exist or read blob contents.

What it does

git cat-file reads objects from the database and prints their type, size, or pretty-printed content. It is the canonical way to verify an object exists and inspect commits, trees, and blobs.

Common usage

Terminal

git cat-file -t HEAD              # object type (commit)
git cat-file -s <sha>             # size in bytes
git cat-file -p HEAD              # pretty-print the object
git cat-file -p HEAD:path/file    # a blob's contents
git cat-file -e <sha> && echo exists

Options

Flag	What it does
-t	Print the object type
-s	Print the object size
-p	Pretty-print the object content
-e	Exit 0 if the object exists (no output)
--batch / --batch-check	Stream many objects efficiently

Common errors in CI

fatal: Not a valid object name <sha> or fatal: git cat-file <sha>: bad file - the object is absent (truncated SHA or a shallow clone missing it). Use -e to test existence first, and ensure full history is present for deep object lookups.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git cat-file: Usage, Options & Common CI Errors?