← Back to Help

Table of Contents

Mercurial Cheat Sheet

A quick reference for working with Mercurial repositories on Isurus.

Getting Started

Clone a Repository

# Clone over HTTP
hg clone https://your-isurus-instance/org/repo

# Clone over SSH
hg clone ssh://your-isurus-instance/org/repo

Configure Your Identity

Add to your ~/.hgrc (or %USERPROFILE%\mercurial.ini on Windows):

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

Daily Workflow

Check Status

# Show modified, added, and removed files
hg status

# Short status format
hg status -q

Add Files

# Add a specific file
hg add myfile.txt

# Add all untracked files
hg add

Commit Changes

# Commit with a message
hg commit -m "Add new feature"

# Commit specific files
hg commit -m "Fix bug" file1.go file2.go

Push and Pull

# Push committed changes to Isurus
hg push

# Pull changes from Isurus
hg pull

# Pull and update working directory
hg pull -u

Update Working Directory

# Update to the latest revision
hg update

# Update to a specific revision
hg update -r REVISION

# Update to a bookmark
hg update my-bookmark

Branching and Bookmarks

Isurus uses bookmarks as the primary lightweight branching mechanism (similar to Git branches).

Working with Bookmarks

# Create a new bookmark
hg bookmark my-feature

# List all bookmarks
hg bookmarks

# Move to a bookmark
hg update my-feature

# Delete a bookmark
hg bookmark -d my-feature

# Push a specific bookmark
hg push -B my-feature

Named Branches

# List all branches
hg branches

# Create a new branch (permanent, rarely needed)
hg branch my-branch

# Show current branch
hg branch

Bookmark-Based Workflow

The typical workflow for contributing to an Isurus repository:

# 1. Clone the repo and update to default
hg clone ssh://isurus-host/org/repo
cd repo
hg update default

# 2. Create a feature bookmark
hg bookmark my-feature

# 3. Make changes and commit
hg commit -m "Implement feature"

# 4. Push the bookmark
hg push -B my-feature

# 5. Create a Pull Request on Isurus from "my-feature" to "default"

History

View Log

# Show recent commits
hg log

# Show last 10 commits, concise
hg log -l 10 --template "{rev}:{short(node)} {desc|firstline}\n"

# Show log for a specific file
hg log myfile.go

# Graphical log
hg log -G

View Differences

# Show uncommitted changes
hg diff

# Show changes in a specific commit
hg diff -c REVISION

# Show diff between two revisions
hg diff -r REV1 -r REV2

# Show diff for a specific file
hg diff myfile.go

Annotate (Blame)

# Show who changed each line
hg annotate myfile.go

# With revision numbers
hg annotate -n myfile.go

Working with Isurus

HTTP Authentication

When cloning or pushing over HTTP, Isurus accepts your username and password (or API token). You can store credentials in ~/.hgrc:

[auth]
isurus.prefix = https://your-isurus-instance
isurus.username = your-username
isurus.password = your-api-token

SSH Authentication

  1. Generate an ED25519 SSH key: 
    ssh-keygen -t ed25519 -C "your@email.com"
  2. Add the public key (~/.ssh/id_ed25519.pub) to your Isurus account under Settings > SSH Keys.
  3. Clone using the SSH URL shown on the repository page.

Clone URLs

Each repository page on Isurus displays both HTTP and SSH clone URLs. Click the URL to copy it.

Phases

Isurus repositories use non-publishing mode, meaning pushed changesets remain in the draft phase until explicitly made public.

# View phases of recent commits
hg log --template "{rev}: {phase} {desc|firstline}\n"

# Make a changeset public
hg phase -p REVISION

# Move a changeset back to draft (only if not pushed)
hg phase -d -f REVISION

Why Phases Matter

  • Draft changesets can be amended, rebased, or stripped.
  • Public changesets are considered immutable and shared.
  • Non-publishing mode lets you push work-in-progress without locking it down.

Undoing Changes

Revert Files

# Revert a specific file to its last committed state
hg revert myfile.go

# Revert all uncommitted changes
hg revert --all

Backout a Commit

# Create a new commit that reverses the changes in REVISION
hg backout -r REVISION

Strip Commits

Requires the strip extension. Add to ~/.hgrc:

[extensions]
strip =

# Remove a commit and all descendants (local only!)
hg strip REVISION

Warning: Only strip changesets that have not been pushed. Stripping shared history causes problems.

Amend the Last Commit

# Amend the most recent commit with current changes
hg commit --amend

Tips

Useful .hgrc Extensions

[extensions]
# Rebase changesets onto a different parent
rebase =

# Strip unwanted changesets
strip =

# Shelve uncommitted changes (like git stash)
shelve =

# Show evolution history
evolve =

[ui]
# Use a merge tool
merge = internal:merge3

# Enable color output
color = auto

[alias]
# Short aliases
st = status
ci = commit
up = update

Common Aliases

[alias]
# Log with graph
lg = log -G --template "{rev}:{short(node)} {bookmarks} {desc|firstline} ({date|age})\n"

# Show current bookmark and branch
where = log -r . --template "{rev}:{short(node)} [{branch}] {bookmarks}\n"

Working with Large Files

If your repository uses the largefiles extension:

[extensions]
largefiles =

hg add --large bigfile.bin