ewl-mercurial

name	ewl-mercurial
description	Mercurial version control for EWL systems; load this skill when a .hg directory is present instead of using Git commands

Overview

EWL and many of its client systems use Mercurial for version control. The repositories are hosted on Heptapod (GitLab with Mercurial support). When working in these repositories, use hg commands instead of git.

This skill maps common Git operations to their Mercurial equivalents and documents EWL-specific conventions.

Detecting the VCS

Check for a .hg directory at the repository root. If present, use Mercurial. If only .git is present, use Git. Never mix the two in the same working copy.

Git-to-Mercurial command mapping

Task	Git	Mercurial
Status	git status	hg status
Diff (working copy)	git diff	hg diff
Diff (staged)	git diff --cached	(no staging area; see below)
Log (recent)	git log --oneline -10	hg log -l 10 --template "{rev}:{short(node)} {desc|firstline}\n"
Log (with graph)	git log --oneline --graph	hg log --graph --template "{rev}:{short(node)} {desc|firstline}\n"
Commit all changes	git add -A && git commit -m "msg"	hg commit -m "msg"
Commit specific files	git add file && git commit	hg commit file1 file2 -m "msg"
Amend last commit	git commit --amend	hg amend (requires Evolve)
Revert a file	git checkout -- file	hg revert file
Revert all files	git checkout -- .	hg revert --all
Pull remote changes	git fetch	hg pull
Update to latest	git pull	hg pull -u
Update to revision	git checkout <ref>	hg update <rev>
Show current revision	git rev-parse HEAD	hg identify
Show current branch	git branch --show-current	hg branch
Push	git push	hg push
Stash changes	git stash	hg shelve
Pop stash	git stash pop	hg unshelve
Create a tag	git tag <name>	hg tag <name>
Merge	git merge <branch>	hg merge <rev>
Rebase	git rebase <base>	hg rebase -d <dest> (requires rebase extension)
Blame/annotate	git blame file	hg annotate file

Piping hg output

When piping hg output through filters, always use grep instead of findstr. On Windows, findstr misparses arguments when the working directory path contains spaces, which closes stdin prematurely and triggers a BrokenPipeError cascade in Mercurial. For example:

# BROKEN -- findstr misparses the path and kills the pipe
hg annotate -u -d -c file.cs | findstr /N "."


# WORKS -- grep handles paths with spaces correctly
hg annotate -u -d -c file.cs | grep -n "pattern"

For large output (e.g. hg annotate on a big file), redirecting to a file and using the Read tool is also reliable:

hg annotate -u -d -c file.cs > annotate_out.txt

Key differences from Git

No staging area

Mercurial has no index/staging area. hg commit commits all modified tracked files by default. To commit only specific files, list them explicitly:

hg commit file1.cs file2.cs -m "Fix widget layout"

To exclude files, use the -X flag:

hg commit -X "*.generated.cs" -m "Manual changes only"

Two separate shelve mechanisms

TortoiseHg and Mercurial have independent shelve implementations that are not interoperable:

	TortoiseHg (GUI)	Mercurial CLI
Storage	.hg/shelves/	.hg/shelved/
Names	Timestamp-based	User-chosen (--name)
List	Shelve tool in GUI	hg shelve --list

TortoiseHg's shelve predates Mercurial's (added in Hg 2.8, 2013). Each tool only sees its own shelves. When working from the command line, always use hg shelve / hg unshelve and be aware that these shelves will not appear in TortoiseHg's Shelve dialog, and vice versa.

Topics instead of branches

EWL repositories use topics (a Heptapod/Evolve feature) for feature work instead of named branches or bookmarks. All work happens on the default branch; topics provide a lightweight, temporary label for in-progress changesets (analogous to Git feature branches). A topic is automatically cleared when its changesets are published (merged to the public phase).

# Start a new topic
hg topic my-feature
hg commit -m "Add feature"


# See the current topic
hg topic


# List all active topics
hg topics


# Switch to an existing topic
hg update my-feature


# Push the current topic
hg push

Do not use hg branch to create named branches (they are permanent and cannot be deleted). Do not use bookmarks either; topics are the standard workflow.

Evolve extension and safe history rewriting

EWL repositories use the Evolve extension, which enables safe history rewriting with obsolescence markers. Key commands:

• hg amend -- amend the current commit (like git commit --amend)
• hg fold -- combine multiple sequential commits into one
• hg prune -- mark a changeset as obsolete (like deleting a commit)
• hg evolve -- automatically resolve unstable changesets after rewriting
• hg next / hg prev -- navigate between changesets in a stack

Obsoleted changesets are hidden but not destroyed. Use hg log --hidden to see them if needed.

EWL conventions

Repository hosting and clone model

Repositories are hosted on Heptapod (heptapod.host). Heptapod uses a multi-clone model: each developer has a named server-side clone, and there is a canonical clone that serves as the authoritative repository. Remote paths are typically configured as:

[paths]
default = https://heptapod.host/enduracode/<project>/<developer-name>
canonical = https://heptapod.host/enduracode/<project>/canonical

To push to your clone: hg push (uses default). To pull from canonical: hg pull canonical.

Branch and topic conventions

All development happens on the default branch (Mercurial's main branch). Feature work uses topics on default.

Build integration

The EWL Development Utility captures the current changeset hash for build tagging using:

hg --debug identify --id

This is invoked automatically during the export/build process. The TortoiseHg installation is expected at C:\Program Files\TortoiseHg\hg.

Commit messages

IMPORTANT: Every line in a commit message MUST be 80 characters or fewer (the TortoiseHg default summarylen). Fill each line with as many words as will fit within the 80-character limit before wrapping to the next line. Do not wrap prematurely (e.g. at 50 characters when more words would fit). Use a literal newline inside the -m argument to break lines:

hg commit -m "Fixed file-upload crash when no file is selected, since ASP.NET
Core represents this as a string form value (not an IFormFile)."

Ignore file

The .hgignore file is auto-generated by the Development Utility. Do not edit it manually. It uses syntax: glob and subinclude directives to incorporate additional ignore patterns from nested .gitignore files:

syntax: glob
subinclude:.opencode/.gitignore