git rev-parse

How it works

Syntax

git rev-parse [<options>] <arg>…

Parameters

Returns

Key points

• Its original job is to split a mixed command line into flags, revision arguments for rev-list, and everything else. The filtering options --revs-only, --no-revs, --flags and --no-flags control which of these groups get printed.
• --verify is the safe way to resolve one name to an object ID. Pass exactly one argument; anything else is an error. Adding a peel such as ^{commit} also makes sure the object exists and has the type you expect.
• --short gives an abbreviated hash that is still unique. If you don't pass a length, it uses core.abbrev.
• --abbrev-ref HEAD is the usual way to print the name of the current branch rather than its commit hash.
• Scripts can find out where they are running. --show-toplevel gives the absolute path of the work tree root, and --show-prefix gives the current directory's path relative to that root.
• The --is-* options print true or false. Use them in scripts to check the current environment, for example whether you are inside a work tree or whether the repository is bare or shallow.
• Use --git-path when you need the location of a file inside the repository directory. It takes relocation variables and linked worktrees into account, so it is safer than building $GIT_DIR/... paths yourself.
• --disambiguate=<prefix> lists every object whose name starts with a short hex prefix, which shows why a short hash is ambiguous. The prefix has a minimum length.

Common mistakes

• If the name comes from user input, put --end-of-options before it. Otherwise an input like --all would be read as an option instead of a revision.
• --parseopt and --sq-quote are operation modes and only work when placed before every other option.
• Date and count reflog suffixes such as main@{yesterday} or main@{1} read the local reflog. They fail if the ref has no reflog, for example right after a fresh clone.
• Most modes need a repository and stop with a fatal error outside one. Only a few, such as --parseopt and --sq-quote, are documented as working anywhere.

Example: Gather repo context safely in a shell script

#!/usr/bin/env bash
set -euo pipefail

# Bail out early if not inside a work tree
if [ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" != "true" ]; then
  echo "not in a git work tree" >&2
  exit 1
fi

root=$(git rev-parse --show-toplevel)
branch=$(git rev-parse --abbrev-ref HEAD)
sha=$(git rev-parse --verify HEAD)
short=$(git rev-parse --short HEAD)

# Validate a user-supplied revision as a commit, quietly
rev="${1:-main}"
if commit=$(git rev-parse --quiet --verify --end-of-options "${rev}^{commit}"); then
  echo "$rev -> $commit"
else
  echo "'$rev' is not a commit" >&2
fi

# Upstream of the current branch, as a full ref (may be unset)
upstream=$(git rev-parse --symbolic-full-name @{u} 2>/dev/null || echo none)

echo "root=$root branch=$branch sha=$sha short=$short upstream=$upstream"

When to use it

Interview questions

Related

• git rev-list
• gitrevisions
• git show-ref
• git symbolic-ref
• git describe
• git merge-base
• git for-each-ref
• git update-ref