Skip to content

Git Revision Specifiers and Range Expressions ​

Every Git command that accepts a commit -- git log, git diff, git rebase, git cherry-pick, git rev-parse, git rev-list -- parses revision specifiers. The specifier language is Git's grammar for talking about commits, and it is far richer than just branch names or SHAs.

For a DevOps engineer writing CI automation, mastering this language means writing scripts that handle detached HEAD, bisect states, stale refs, and complex boundary queries without fragile workarounds.

The revision grammar in one sentence ​

Every specifier resolves to a single commit SHA (or fails with an error). Range expressions resolve to a set of commits. The grammar composes: you can build expressions like HEAD~3^{/fix:}@{5 minutes ago} and Git will parse them left to right.

Single-commit specifiers ​

SHA and abbreviations ​

bash
git rev-parse a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
git rev-parse a1b2c3d       # unique prefix, minimum 4 chars

Git resolves unique prefixes. If the prefix is ambiguous (two objects start with the same characters), Git errors with the list of matches.

Ref names ​

bash
git rev-parse main               # branch
git rev-parse v2.0.0             # tag (lightweight or annotated)
git rev-parse HEAD               # current commit
git rev-parse FETCH_HEAD         # last fetched tip
git rev-parse ORIG_HEAD          # backup of HEAD before dangerous ops
git rev-parse MERGE_HEAD         # other side of an in-progress merge
git rev-parse CHERRY_PICK_HEAD   # commit being cherry-picked (during conflict)
git rev-parse BISECT_BAD         # current bad mark during bisect

HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD, CHERRY_PICK_HEAD, and BISECT_BAD are special refs Git updates automatically during operations. CI scripts should check they exist before dereferencing: git rev-parse --verify ORIG_HEAD 2>/dev/null || echo "no ORIG_HEAD".

Remote-tracking branches ​

bash
git rev-parse origin/main
git rev-parse upstream/feature-branch
git rev-parse origin/HEAD          # the default branch on origin

HEAD~N: parent by generation ​

bash
HEAD        # the current commit
HEAD~       # the first parent (same as HEAD~1)
HEAD~2      # the first parent of the first parent
HEAD~3      # three generations back
main~5      # five commits before main, following first-parent chain

The tilde follows the first parent chain. On a merge commit, ~ always follows the mainline (the branch you were on when you merged), skipping the merged branch entirely. This makes ~ the right choice for linear traversal.

HEAD^N: parent by merge order ​

bash
HEAD^       # first parent (same as HEAD~1)
HEAD^1      # first parent
HEAD^2      # second parent (the branch that was merged in)
HEAD^3      # third parent (octopus merge only)

On a regular commit, ^1 is the only parent and ^2 is invalid. On a merge commit, ^1 is the branch you were on, ^2 is the branch you merged. Octopus merges can have 3+ parents.

Combine them:

bash
HEAD~2^2        # go back 2 generations, then take the second parent
HEAD^2~3        # go to the merged branch's tip, then back 3 commits

HEAD@{N}: reflog by position ​

bash
HEAD@{0}        # current position of HEAD
HEAD@{1}        # where HEAD was before the last operation
HEAD@{5}        # 5 operations ago
main@{yesterday}  # where main was yesterday
main@{1.week.ago}
main@{2026-11-10}

Reflog specifiers resolve from the local reflog. They are not transferable across clones. CI scripts that use them for rollback detection must check the reflog exists.

@{upstream}: the tracked remote branch ​

bash
@{u}            # upstream of current branch
@{upstream}
main@{u}        # upstream of main
main@{upstream}

Resolves to the tracking branch configured via git branch -u. Errors if no upstream is set.

@{push}: the push destination ​

bash
@{push}         # the branch that `git push` would send to
main@{push}

Same as @{u} unless push.default is set to tracking and the push remote differs from the fetch remote.

:/text: find a commit by message ​

bash
:/fix login         # most recent commit with "fix login" in message
:/^Merge            # most recent merge commit
:/^chore:           # most recent commit starting with "chore:"
:/"security patch"  # literal string with space, quoted

Searches commit messages (subject + body) in the reachable commit graph. Returns the newest commit matching the regex. Use :/^ to anchor at the start of the message.

:<path>: blob at a commit ​

bash
:README.md                 # blob from index (staged state)
:0:README.md               # same, stage 0 (no conflict)
:1:README.md               # merge base stage during conflict
:2:README.md               # "ours" stage during conflict
:3:README.md               # "theirs" stage during conflict
HEAD:src/main.c            # blob at HEAD
main~3:package.json        # blob at main~3

The stage numbers (:0: through :3:) are useful in merge conflict automation. Stage 0 is the normal state. During a conflict, stages 1-3 hold the three-way merge inputs.

^{type}: peel to object type ​

bash
v2.0.0^{commit}    # the commit an annotated tag points to
v2.0.0^{tree}      # the tree object of that commit
HEAD^{tree}        # the root tree of HEAD
main^{blob}:README  # (rare) blob if the ref directly points to one

Without peeling, an annotated tag's SHA resolves to the tag object, not the commit. CI scripts that need the commit SHA must use ^{commit} or the shorthand v2.0.0^{} (peel to any non-tag object).

@{-N}: previously checked-out branch ​

bash
@{-1}           # the branch you were on before this one
@{-2}           # two switches ago

Useful in aliases: git checkout @{-1} is faster than remembering the branch name.

^! and ^@: parent shorthands ​

bash
HEAD^!          # the commit itself, excluding its parents (for `git show`)
HEAD^@          # all parents of HEAD, not the commit itself

^! is useful in CI to verify a commit is a root commit (no parents): git rev-parse HEAD^! errors if HEAD has no parents.

Range expressions ​

Range expressions produce a set of commits (for git log, git rev-list, git diff, etc.).

X..Y (two-dot): commits reachable from Y but not from X ​

bash
git log main..feature          # commits on feature not on main
git log --oneline v1.0..v2.0   # commits between two tags
git rev-list --count HEAD..@{u} # how many commits upstream has that you don't

The left side is the exclude boundary. The right side is the include boundary. Order matters: main..feature is not the same as feature..main.

X...Y (three-dot): symmetric difference ​

bash
git log main...feature          # commits in either branch but not both
git diff main...feature         # changes introduced by feature relative to its merge base
git rev-list --left-right main...feature  # labelled left/right

Three-dot shows commits reachable from either ref but not from both. This is the set Git uses for git status when it says "your branch and origin/main have diverged."

With --left-right, git rev-list prefixes each commit with < (left side only) or > (right side only). Count them:

bash
git rev-list --left-right --count main...feature
# 3    5   (3 on main only, 5 on feature only)

X^@ and X^! in ranges ​

bash
git log HEAD^@..HEAD            # commits since the last merge base
git show HEAD^!                 # just the diff of the last commit

--since= and --until= as range filters ​

These are not specifiers but the most common way to bound a range by time in CI:

bash
git rev-list --count --after="2026-11-01" --before="2026-11-10" main
git log --after="2 weeks ago" --until="yesterday" --oneline

They accept ISO 8601 dates, relative dates ("2 weeks ago", "3 days ago"), and reflog-style dates ("yesterday", "1 week ago").

Composition examples ​

All these compose left to right:

bash
# What did the last 3 commits on main change?
git diff HEAD~3..HEAD

# What's in the feature branch relative to its merge base with main?
git diff main...feature

# Show commits in the upstream that aren't in current branch
git log --oneline HEAD..@{u}

# Who committed to the second-parent chain of a merge?
git log --author="jane" HEAD^2~5..HEAD^2

# The tree of the commit that introduced "fix auth"
git rev-parse :/fix auth^{tree}

# The blob from the first parent of a merge, two generations back
git show HEAD~2^1:src/config.json

# Is the current state ahead of what we pushed last?
git rev-list --count @{push}..HEAD

Quick reference table ​

SyntaxResolves toUse case
HEADCurrent commitEvery script
HEAD~NNth first-parent ancestorLinear traversal
HEAD^NNth parent (merge order)Inspecting merged branches
@{N}Nth reflog entryRecovery, rollback detection
@{u}Upstream tracking branchBranch-agnostic automation
:/textNewest commit matching messageFinding commits without SHAs
:pathBlob at a commit or indexZero-checkout file extraction
^{tree}Tree object of a commitPlumbing operations
@{-N}Previously checked-out branchBranch switching automation
X..YCommits in Y not in XStandard diff/log range
X...YSymmetric differenceDivergence analysis
X^!Commit X only (no parents)Single-commit diff
X^@Parents of X onlyMerge parent enumeration

Pitfalls ​

PitfallWhy it bitesFix
HEAD~ on a merge commit follows first parent onlyYou skip the merged branch's commitsUse HEAD^2 to reach the merged branch
:/text matches the newest reachable commitA fix commit on a stale branch can match instead of the one you wantNarrow with :/text -- main or specify a range
@{N} resolves from the local reflogDifferent machine, different reflogNever hardcode reflog positions in CI
^{} peels annotated tags but git describe output may include the tag namegit rev-parse v1.0 gives the tag object, not the commitAlways use v1.0^{commit} in CI scripts
origin/main is a local snapshotIt may be stale; you must git fetch firstRun git fetch origin before reading origin/main
main..feature and feature..main are oppositesThey produce different commit setsThink "exclude left, include right"
git diff main...feature vs git diff main..featureThree-dot diffs from merge base; two-dot diffs tip-to-tipThree-dot is usually what you want for review
:1:path during a conflictStage 1 is the merge base, not "ours":2: = ours, :3: = theirs

Why this matters in CI ​

Every CI script that touches Git resolves specifiers. Getting them wrong silently breaks automation:

bash
# Bad: assumes annotated tag peels to commit
DEPLOY_SHA=$(git rev-parse "$CI_COMMIT_TAG")

# Good: explicit peel
DEPLOY_SHA=$(git rev-parse "${CI_COMMIT_TAG}^{commit}")

# Bad: reads origin/main without fetch
if git merge-base --is-ancestor origin/main HEAD; then ...

# Good: fetch first
git fetch origin
if git merge-base --is-ancestor origin/main HEAD; then ...

When your deploy gate, regression detector, or backport bot uses the wrong specifier, it does not fail loudly. It resolves to the wrong commit and proceeds. Testing specifier resolution in a dry-run step catches these before they reach production.

Next steps ​

With specifiers mastered, the rev-parse guide shows how to use them in CI scripts. The rev-list guide covers traversal options like --first-parent, --bisect, and --cherry. The range-diff guide shows how to compare entire patch series between the old and new version of a rebased branch.

Git Master — Git Reference for Every Skill Level