---
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`:

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

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

```sh
hg commit -m "your message"
```

## Inspection commands

| Need | Command |
|---|---|
| What changed in working dir | `hg status` |
| Diff of unstaged changes | `hg diff` |
| Recent commits | `hg log` (or `hg log -l 10` for limit) |
| Working dir parent revision | `hg parents` |
| All current heads | `hg heads` |
| Named branches | `hg branches` |
| Bookmarks (≈ feature branches) | `hg bookmarks` |
| Phase of a revision | `hg phase -r <rev>` |
| Who wrote each line | `hg annotate <file>` (git users: `blame`) |

## 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

```sh
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:

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

See recent history on a bookmark:

```sh
hg log -l 5 -B my-feature
```

Diff between two revisions:

```sh
hg diff -r REV1 -r REV2
```