Querying Mercurial History with Revsets: A Practical Guide

The Problem: Noisy History

When a repository grows, hg log without filters drowns you in changesets that are irrelevant to the task at hand. Shell pipelines with grep, awk, or sed become fragile and hard to share across a team.

Revset Basics

Mercurial’s revset language lets you describe the exact set of revisions you need using a compact, SQL‑like syntax. Predicates such as branch(), tag(), date(), ancestor(), and file() can be combined with Boolean operators (and, or, not) and modifiers like limit() or sort(). The feature has been stable since Mercurial 2.0 and requires no extra plugins.

Worked Example: Reviewing a Feature Branch

Suppose you want every commit on the feature/login branch that appeared after the v1.2.0 tag. Run the following command from the repository root (no special permissions needed):

hg log -r "branch(feature/login) and >= tag('v1.2.0')"

Mercurial evaluates the revset, walks only the relevant ancestry, and prints the matching changesets. Compare the output with a traditional pipeline:

hg log --branch feature/login | awk '/v1\.2\.0/ {found=1} found'

The revset version is shorter, easier to read, and produces identical results when the tag exists.

Performance Trade‑offs

• Simple revsets (branch, tag, date, limit) are fast because they use the internal index.
• Predicates that inspect file contents (file()) or run regular expressions can trigger full‑history scans on large repositories.
• Deep ancestry walks (e.g., ancestors('tip') and descendants('root')) may be slower than a focused hg log --follow.

For performance‑critical scripts, benchmark the revset against a narrower hg log invocation before committing to it.

Getting Started Today

1. Verify your Mercurial version:

   hg --version
   

   Ensure the reported version is 2.0 or higher.

2. Explore built‑in help:

   hg help revset
   

3. Test a minimal revset in a disposable clone:

   hg log -r "branch(default) and limit(5)"
   

   You should see the five most recent changesets on the default branch.

4. Persist useful revsets as aliases in .hgrc (user or repo level):

   [alias]
   recent = log -r "branch(default) and limit(10)"
   stable = update -r "branch(stable) and not closed()"
   

   Now hg recent and hg stable run the revsets without retyping.

Adopting revsets reduces noise, makes scripts portable, and keeps history queries readable for the whole team.