name: mercurial-basics
description: Use when working in any Mercurial repository for inspection or local commits — hg status, diff, log, add, commit, parents, heads, branches, bookmarks, phase. Triggers on any hg ... command or when .hg/ is in the working directory.

Mercurial basics

When this applies

Use when:

• The working directory contains .hg/ (or any ancestor does).
• About to run any hg command.
• About to perform an operation that has both git and hg equivalents and the repo is hg.

Do not use for:

• Pulling, merging, conflict resolution → see mercurial-sync-and-merge.
• Bookmarks and the PR workflow → see mercurial-bookmarks-and-prs.
• Amending or rewriting history → see mercurial-history-rewriting.

Identity comes from ~/.hgrc

Never pass -u to hg commit. Identity is configured globally in ~/.hgrc:

[ui]
username = Name <email@example.com>

hg commit -u "..." is for impersonation and will create commits with the wrong author. Always:

hg commit -m "your message"

Inspection commands

Reading hg log output

Default format shows changeset hash, branch (if not default), tag, user, date, and summary:

changeset:   42:a1b2c3d4e5f6
branch:      myfeature
tag:         tip
bookmark:    work-in-progress
user:        Alice <alice@example.com>
date:        Mon May 02 09:00:00 2026 -0500
summary:     feat: add the thing

For terser output: hg log --template '{node|short} {bookmarks} {branch} {desc|firstline}\n'

Commit messages

The Isurus convention (and a generally good rule) is:

• First line: imperative summary, under 72 characters. Examples: feat: add language stats to repo sidebar, fix: handle nil reviewer in PR template, chore: bump dependency X to v2.
• Body (optional): explain why the change is being made. The diff already shows what. One blank line between summary and body.
• Category prefix (feat:, fix:, docs:, chore:, test:, refactor:) is convention in this codebase — match what hg log shows.

Keep each commit focused. If a single change touches unrelated areas, split into separate commits.

Adding files

hg add path/to/file       # explicit
hg add                    # add all untracked files (use carefully)

Mercurial does not have a staging area. Files are tracked or not; commits include all changes to tracked files. To commit only some changes, use hg commit path/to/file1 path/to/file2.

.hgignore syntax

.hgignore lives at the repo root. Default syntax is glob:

syntax: glob

# Build artifacts
dist/
*.o

# Switch syntax for a section
syntax: rootglob
binary-at-root-only

# Switch back
syntax: glob
**/*.swp

syntax: rootglob matches only at the repo root (useful for binary names that must not match files in subdirectories).

Phase awareness

Every changeset has a phase: draft, public, or secret. The phase governs what's safe to rewrite:

• draft — local or pushed-but-not-merged. Safe to amend, uncommit, rewrite.
• public — published and considered immutable.
• secret — never pushed.

In a non-publishing repo (like Isurus), pushed changesets stay draft until merged into the canonical branch. This is what makes hg amend safe during code review. See mercurial-history-rewriting for the rewriting rules.

To check: hg phase -r <rev>. To see your tip: hg phase -r tip.

Common workflow examples

Inspect what's changed and commit:

hg status
hg diff
hg add new-file.go
hg commit -m "feat: add new thing"

See recent history on a bookmark:

hg log -l 5 -B my-feature

Diff between two revisions:

hg diff -r REV1 -r REV2