# Mercurial Hg

> Use for version-control work on a confirmed Mercurial (Hg) working copy or an explicitly identified Mercurial target. Do not activate merely because Hg is mentioned in a comparison, migration discussion, or separate Git repo.

- Skill: `yantyx/mercurial-hg` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add yantyx/mercurial-hg`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yantyx/mercurial-hg/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yantyx (https://skillmd.com/u/yantyx)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/yantyx/mercurial-hg

---


# Mercurial (Hg) Version Control

Use this skill for operations that actually target a Mercurial repository. A
user can ask about Hg while working in a Git repository; that comparison does
not make the Git repository Mercurial or prohibit Git commands there. Confirm
the target before choosing a VCS workflow:

```bash
hg root
hg status
hg diff
```

`hg root` establishes the working-copy root. `hg status` and `hg diff` show
what would be affected. If `hg root` fails, stop treating that directory as an
Hg working copy. For a separate Git repository, use its Git workflow. An
explicit remote or path identified as Mercurial may be handled as Hg even
before a local working copy exists.

## Safety gate

Discovery is read-only and comes first: resolve the target with `hg root`,
then inspect `hg status` and `hg diff`. Before a destructive or
history-rewriting command, identify the exact files or revisions, explain what
can be lost, and get explicit authorization. This applies to `hg remove`,
`hg revert`, `hg update -C`, purge, rollback, strip/debugstrip, histedit drops,
and destructive subrepository removal. Prefer a narrow file or revision target
and a recoverable alternative.

For “undo my last commit but keep the files,” do not immediately run rollback
or strip. Inspect first, run `hg help -e uncommit` to see whether that
extension is available, explain the proposed history rewrite, and ask for
confirmation. `hg rollback` is deprecated and transaction-based, not routine
undo. `hg recover` is only for an interrupted transaction when Mercurial asks
for it. See [extensions](references/extensions.md) for those boundaries.

## Core terms

Mercurial has no staging area: a normal `hg commit` includes the outstanding
changes selected by its file arguments, or all changes reported by `hg status`
when none are supplied. A changeset has a hash and a local revision number.
`.` is the checked-out parent; lowercase `tip` is the newest revision in the
repository, not necessarily the checked-out parent. A named branch is recorded
in history; a bookmark is a movable label. See [branching](references/branching.md)
and [migration](references/migration.md) before translating Git terminology.

## Safe daily commands

```bash
hg status                 # working-copy state
hg diff                   # uncommitted changes against the parent
hg log -r .               # checked-out parent
hg log -r REV -p          # a changeset and its patch
hg add FILE               # start tracking a file
hg forget FILE            # stop tracking while keeping it on disk
hg commit -m "message"    # commit outstanding changes
hg pull                   # fetch from the default path
hg push                   # publish changesets
hg incoming               # inspect incoming changesets
hg outgoing               # inspect outgoing changesets
hg paths                  # configured remote paths
```

Use `hg update TARGET` to switch to an explicit revision, named branch,
bookmark, or tag. Plain `hg update` instead means update to the tip of the
current named branch. Use `hg branch NAME` only to set the name recorded by the
next commit; it does not switch to an existing named branch. For an existing
`release` branch, use `hg update release`.

Shelves are the stash-like mechanism: use `hg shelve`, `hg shelve -n NAME`,
`hg unshelve`, and `hg unshelve NAME`. To publish a bookmark label, use
`hg push -B NAME`; `hg push -r NAME` transfers a revision and its ancestors,
but does not publish the bookmark label. Search the working copy with `hg grep
PATTERN`; search history only with `hg grep --rev REVSET PATTERN`.

For command-specific options and behavior, start with `hg help COMMAND`.
Route named-branch, bookmark, merge, and rebase work to
[branching](references/branching.md); extension, recovery, and subrepository
work to [extensions](references/extensions.md); and Git/Mercurial translation
or conversion questions to [migration](references/migration.md). For official
revision guidance, see [Mercurial's revision documentation](https://mercurial-scm.org/help/topics/revisions).