1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
---
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
```
|