Appearance
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 charsGit 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 bisectHEAD, 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 originHEAD~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 chainThe 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 commitsHEAD@{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, quotedSearches 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~3The 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 oneWithout 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 agoUseful 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'tThe 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/rightThree-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" --onelineThey 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}..HEADQuick reference table
| Syntax | Resolves to | Use case |
|---|---|---|
HEAD | Current commit | Every script |
HEAD~N | Nth first-parent ancestor | Linear traversal |
HEAD^N | Nth parent (merge order) | Inspecting merged branches |
@{N} | Nth reflog entry | Recovery, rollback detection |
@{u} | Upstream tracking branch | Branch-agnostic automation |
:/text | Newest commit matching message | Finding commits without SHAs |
:path | Blob at a commit or index | Zero-checkout file extraction |
^{tree} | Tree object of a commit | Plumbing operations |
@{-N} | Previously checked-out branch | Branch switching automation |
X..Y | Commits in Y not in X | Standard diff/log range |
X...Y | Symmetric difference | Divergence analysis |
X^! | Commit X only (no parents) | Single-commit diff |
X^@ | Parents of X only | Merge parent enumeration |
Pitfalls
| Pitfall | Why it bites | Fix |
|---|---|---|
HEAD~ on a merge commit follows first parent only | You skip the merged branch's commits | Use HEAD^2 to reach the merged branch |
:/text matches the newest reachable commit | A fix commit on a stale branch can match instead of the one you want | Narrow with :/text -- main or specify a range |
@{N} resolves from the local reflog | Different machine, different reflog | Never hardcode reflog positions in CI |
^{} peels annotated tags but git describe output may include the tag name | git rev-parse v1.0 gives the tag object, not the commit | Always use v1.0^{commit} in CI scripts |
origin/main is a local snapshot | It may be stale; you must git fetch first | Run git fetch origin before reading origin/main |
main..feature and feature..main are opposites | They produce different commit sets | Think "exclude left, include right" |
git diff main...feature vs git diff main..feature | Three-dot diffs from merge base; two-dot diffs tip-to-tip | Three-dot is usually what you want for review |
:1:path during a conflict | Stage 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.