git rev-parse

Turn HEAD~3 / origin/main / :/typo / etc. into a SHA.

🎯 What & why

git rev-parse turns any revision spec - HEAD~3, origin/main, :/typo, v1.0^{commit} - into a concrete SHA. It also exposes repo layout facts.

🧠 Mental model

Two jobs in one binary: (1) resolve names to OIDs, (2) answer 'where am I?' questions about the current repo. Every shell-script-flavored Git tool calls it.

🛠️ Synopsis

git rev-parse [<options>] <args>...

  git rev-parse HEAD                  # full SHA of HEAD
  git rev-parse --short=8 HEAD        # 8-char abbreviation
  git rev-parse --abbrev-ref HEAD     # 'main' instead of refs/heads/main
  git rev-parse --show-toplevel       # absolute path to repo root
  git rev-parse --is-inside-work-tree # 'true' or 'false'

🎚️ Switches & options

Flag	What it does
`<args>`	Revision specs or option flags to resolve
`--verify`	Require args to resolve to exactly one object; exit nonzero otherwise
`--short[=<n>]`	Abbreviate output SHAs to the shortest unique prefix (or n chars)
`--symbolic`	Print the input symbolic name when it is one
`--symbolic-full-name`	Expand to full ref name (refs/heads/main)
`--abbrev-ref[=<mode>]`	Shorten to short ref name (main, origin/main)
`--git-dir`	Print the path to the .git directory
`--show-toplevel`	Print the absolute path to the working-tree root
`--is-inside-work-tree`	Print true/false: are we inside a working tree
`--is-bare-repository`	Print true/false: is this a bare repo
`--git-common-dir`	Print the common .git dir (matters for worktrees)

💡 Use cases

Validate a user-supplied ref before passing it to a destructive command.
Get the repo root in a shell script that may be run from any subdirectory.
Distinguish bare repos, worktrees, and inside/outside-tree contexts in tooling.
Convert HEAD or a tag to a stable SHA for build artifact tagging.

🧪 Examples

Full SHA of a ref

git rev-parse HEAD

Validate a ref exists

git rev-parse --verify --quiet refs/heads/feature

Find repo root in scripts

ROOT=$(git rev-parse --show-toplevel)

Current branch name

git rev-parse --abbrev-ref HEAD

🎓 Recommendations

Always pair --verify with --quiet in scripts - clean exit code, no noisy stderr.
Use --show-toplevel (not pwd) to anchor scripts; it works from any subdirectory and respects worktrees.
Prefer --git-common-dir over --git-dir when worktrees are in play - it points to the shared object/ref store.

🪤 Common pitfalls

rev-parse happily resolves ambiguous names; in scripts, always pin to refs/heads/X or refs/tags/X.
--abbrev-ref on a detached HEAD prints 'HEAD', not a SHA - check for that case.
Inside a .git directory, --is-inside-work-tree is false but --is-inside-git-dir is true; do not assume one implies the other.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.