Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 78 ยท Inspecting History

Revision Syntax: Naming Commits

Master Git revision syntax: HEAD~2 vs HEAD^2, @{n}, @{upstream}, :/text, rev:path, A..B vs A...B ranges, rev-parse and rev-list, with runnable examples.

Almost every Git command that does something interesting takes a revision: git show, git diff, git reset, git cherry-pick, git rebase, git log. Copying 40-character hashes around works, but it is slow and error-prone. Git has a small, precise language for naming commits relative to things you already know: "the commit before the tip of main", "what HEAD was three moves ago", "the newest commit whose message mentions invoice".

This lesson teaches that language. It looks like punctuation soup at first (HEAD~2^2, main@{1}, A...B), but it has about a dozen building blocks, and once you know them you can express exactly the commits you mean, especially for ranges. We will use two plumbing helpers to see the answers: git rev-parse turns a revision into a hash, and git rev-list lists the commits in a range.

A history to practice on

Every example below uses the same history, built by a short script: a main branch, a feature branch that was merged back in, and a few more commits.

TEXT
A---B---C-------M---N        main
     \         /
      D---E---F              feature (merged into main by M)

M is a merge commit: its first parent is C (the branch you were on) and its second parent is F (the branch you merged).

Bash Build the practice history and look at it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The real graph has the same shape as the picture, with N on top and D, E, F on the side branch.

Hashes and abbreviations

The most direct name for a commit is its full 40-character hash (64 characters in SHA-256 repositories). Git accepts any unambiguous prefix, usually 7 to 12 characters. If two objects share your prefix, Git says the prefix is ambiguous and asks for more characters. git rev-parse --short <rev> prints the shortest unique abbreviation; --short=12 sets a minimum length.

Large repositories automatically use longer abbreviations. In scripts, never hard-code a length. Ask Git.

Refs: names that point to commits

A ref is a name that holds a hash: branches (main), tags (v1.2), remote-tracking branches (origin/main), and special names such as HEAD. When you write main, Git resolves it in a fixed order (.git/main, refs/main, refs/tags/main, refs/heads/main, refs/remotes/main, ...), so a tag and a branch with the same name cause confusing results. Avoid that. You can always be explicit: refs/heads/main or heads/main.

HEAD is your current position, normally the branch you have checked out. Two relatives are worth knowing:

  • ORIG_HEAD: where HEAD was before a dangerous operation (reset, merge, rebase). It is the quick undo for those.
  • MERGE_HEAD, FETCH_HEAD, CHERRY_PICK_HEAD: set during or after specific operations. FETCH_HEAD is the tip you just fetched.

@ alone is a shortcut for HEAD, which is handy: git show @~2.

Walking back: ~ and ^

These two suffixes look alike and behave differently on merge commits.

Syntax Meaning
rev~ or rev~1 the first parent of rev
rev~3 the first parent, three times: great-grandparent along the first-parent line
rev^ or rev^1 the first parent of rev
rev^2 the second parent of rev (only merges have one)
rev^0 rev itself, peeled to a commit (useful with tags)

For a linear history, HEAD~2 and HEAD^^ mean the same. The difference appears with merges: ~n always follows first parents n times, while ^n selects the n-th parent once. They combine from left to right: HEAD~1^2 means "go to the first parent of HEAD, then take its second parent".

Bash Following parents with ~ and ^

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Read the results line by line. HEAD~2 is C, because from N the first parent is M, and the first parent of M is C. HEAD~1^2 is F, the tip of the merged branch. HEAD~1^2~2 walks from F back two steps along the feature branch to D. The commits D, E, F are never reached with plain ~ from main, because ~ follows only the first-parent line.

If you remember one thing: ~ goes back in time along the main line, ^ picks among the parents of a merge. In everyday work on linear history you will almost only write HEAD~1, HEAD~3, and so on.

On Windows cmd.exe, the caret is an escape character, so HEAD^ may need quoting ("HEAD^") or doubling. PowerShell and Git Bash are fine. Using ~ avoids the problem.

Searching by message: :/text

:/text names the youngest commit reachable from any ref whose message matches the regular expression text. Prefix a revision to restrict the search to history reachable from it: main^{/fix} is the newest commit reachable from main whose message contains fix.

  • :/invoice finds the newest commit anywhere (any branch) mentioning "invoice".
  • HEAD^{/^Merge} finds the newest merge message above HEAD.
  • :/!-fix negation uses !-, and :/!! escapes a literal leading !.

It is convenient for quick looks (git show :/typo) but fragile for scripts: a new commit with similar text silently changes the answer.

Names for a path: rev:path and :path

rev:path names a file (a blob) or directory (a tree) as it was in that revision. It is not a commit, but commands that accept objects take it: git show HEAD~3:README.md prints an old version of a file without checking anything out. A bare :path (or :0:path) means the file as it is in the index, and :2:path or :3:path give the "ours"/"theirs" stages during a merge conflict.

Two more suffixes peel an object to a type: rev^{commit} (a tag to its commit), rev^{tree} (a commit to its snapshot tree), and rev^{} (peel until it is no longer a tag).

Bash Messages, paths and peeling

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The index copy differs from HEAD, which is how you can compare "what I staged" with "what is committed" using git diff between these names. Note that v1 itself is a tag object (an annotated tag has its own object); v1^{commit} reaches the commit it points to.

Reflog syntax: @{n}, @{-n} and time

Git keeps a journal for each ref, the reflog, recording where it pointed over time (see The Reflog and Recovering Lost Work). The @{...} syntax reads it:

Syntax Meaning
HEAD@{0} the current value of HEAD
HEAD@{2} where HEAD was two moves ago
main@{3} where the branch main pointed three updates ago
@{-1} the branch you were on before the current one (checkout history)
main@{yesterday}, main@{2.weeks.ago} the value at that time, on this machine
@{upstream} or @{u} the remote-tracking branch main is set up to follow
@{push} the branch git push would update

Reflog entries are local and expire (90 days by default for reachable entries). Time-based forms only know about what your clone recorded, so main@{last.month} in a fresh clone is not real history, and Git warns about it.

Bash @{n}, @{-1} and @{upstream}

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

@{upstream}..HEAD is one of the most useful ranges in daily work: "what have I committed that is not yet on the server?" Next we look at ranges properly.

Ranges: A..B, A...B and ^A

A single revision names one commit, but Git commands like log also accept sets of commits. A revision on its own means "this commit and all its ancestors". Range syntax adds and removes such sets:

Syntax Set of commits
B B and everything reachable from it
^A exclude A and everything reachable from A
A..B reachable from B but not from A (same as ^A B)
A...B reachable from either, but not from both (the symmetric difference)
B --not A C reachable from B, excluding anything reachable from A or C
--all, --branches, --tags, --remotes start from all refs, only branches, only tags, only remote branches

Read A..B as "what does B have that A doesn't". It is the right tool for questions like "what is in my feature branch that is not yet on main?" (main..feature), and ... for "what differs between these two branches, from both sides?" With git log --left-right you can tell the sides apart (< for the left, > for the right).

Bash Two dots, three dots and exclusions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The three-dot form shows five commits (three from main, two from feature), all the commits since the common ancestor B. git rev-list --left-right --count main...feature prints the two counts in one line, which is the data behind "ahead 2, behind 3" in many prompts and status lines. The merge base, the point where the histories split, is git merge-base.

.. and ... mean different things for diff than for log. In git log, A...B is the symmetric difference described above. In git diff, A..B is the same as A B (compare the two tips directly), while A...B compares B against the merge base of the two, so you see only what B changed since the branches split. See Comparing Commits, Branches and Files.

rev-parse and rev-list: the scripting tools

These two plumbing commands are what scripts and aliases are built on.

  • git rev-parse <rev> resolves a name to a full hash. Options: --short, --abbrev-ref (print main instead of a hash), --verify (fail with a non-zero exit code if the name does not resolve to exactly one object), --show-toplevel (the repository root), --git-dir, --is-inside-work-tree.
  • git rev-list <range> prints the hashes of the commits in a range, newest first. Options: --count, --reverse, --max-count=N, --first-parent, --merges, --no-merges, --since=..., --author=..., --objects.
Bash rev-parse and rev-list in scripts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

--first-parent is a key trick on projects that merge feature branches: it shows only the commits on the mainline, which is the list of merges and direct commits, hiding the work inside each branch. We use it often for release notes.

Putting it to work

A few revision expressions that professionals type every week:

Terminal
git diff @{upstream}               # what differs from the remote branch
git log @{upstream}..               # my unpushed commits ("..HEAD" with an empty right side)
git log ..@{upstream}               # commits I have not merged from the remote yet
git rebase -i HEAD~5                # tidy the last five commits
git show :/"fix login"              # newest commit mentioning "fix login"
git checkout -                       # switch back to the previous branch (same as @{-1})
git reset --soft HEAD~1             # undo the last commit, keep changes staged
git log --first-parent --oneline main   # only the mainline
git log --branches --not --remotes  # commits on local branches never pushed anywhere

(These are examples to read, not run; the sandbox has no network remote.) An empty side of .. means HEAD, so @{u}.. and ..@{u} are quick forms of the same ranges.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In a history where HEAD is a merge commit, what does HEAD^2 refer to?

    ^n selects the n-th parent once. HEAD~2 would be the two-step walk along first parents.
  2. 2. Which command lists the commits that feature has but main does not?

    A..B means reachable from B and not from A, so main..feature is what feature adds on top of main. The reverse range answers the opposite question.
  3. 3. What does git log --left-right main...feature show?

    Three dots is the symmetric difference. --left-right adds a mark for which side each commit comes from.
  4. 4. You want a script to fail clearly when a user passes a name that is not a real revision. Which command is best?

    --verify makes rev-parse succeed only if the name resolves to exactly one object, and -q keeps the error quiet so your script can print its own message.
  5. 5. What does @{-1} mean?

    @{-N} reads the checkout history in the reflog. git switch - and git checkout - use the same idea.

Summary

  • A revision can be a hash prefix, a ref (main, v1.2, HEAD, @) or an expression built from them.
  • rev~n walks back n first parents; rev^n picks the n-th parent of a merge once.
  • :/text finds the newest commit by message; rev:path names a file as of a revision; rev^{tree} and rev^{commit} peel objects.
  • @{n}, @{-n}, @{upstream} and @{yesterday} read the reflog or the tracking configuration.
  • A..B = in B, not in A. A...B = in either, not both. --not and ^ exclude. In diff, the dots mean something different.
  • git rev-parse resolves names; git rev-list enumerates commits. Use --verify and --count in scripts.

Next: Comparing Commits, Branches and Files