May 28, 2015

Helix Versioning Engine for Hg Users

Media & Entertainment

As I said recently when offering advice for Git users, the new DVCS features of Perforce Helix are easy to use, but making the transition from another system always involves climbing a learning curve. The purpose of today’s post is to provide some guidance specifically for Mercurial (Hg) users.


Let’s start with some basics. Hg supplies only DVCS features and was developed with a particular eye toward simplifying branching and merging. In contrast, Helix was developed with a more broadly based feature set for a wider variety of workflows/needs. Yet Hg and Helix actually have more in common than one might otherwise expect.


For starters, work-in-progress is handled similarly by Hg and Helix. Modifications to versioned files are part of your next commit by default, so the only operations an Hg user typically expects to “tell” the system about are file adds and deletes.

This is usually handled via the “hg add” and “hg remove” commands, but the “hg addremove” command is a third alternative. It adds all new files and removes all missing files previously tracked with a single command. I mention this because the Helix reconcile command achieves a similar end result.

The main difference is that while Hg includes modifications automatically, Helix does not. Helix maintains all work-in-progress via a concept known as a changelist, and in particular your DVCS work-in-progress is maintained in a changelist named “default”.

Hg users largely don’t need to worry about this. Simply run the reconcile command to prepare for a commit, and it will include all adds, deletes, and modifications in your default changelist.


Hg users have long enjoyed shelving as a feature, previously as an extension and natively since the v2.8 release. Shelving in Helix is similar but differs in that Hg shelves can be named whereas Helix shelves are a unary feature of a changelist, which is numbered and has a description instead. For example, the default changelist has one shelf where work in progress will be saved automatically when switching branches or what not.


In Hg parlance, a “path” is a “pointer” from/to which content may be cloned/pushed, whereas Helix users know these as “remote specifications” or just “remotes” for short. Further, an Hg “path” offers only a small subset of what Helix offers. A Helix remote specification is much more powerful insofar as it includes the ability to map content very selectively.[1] Folders and files may be flexibly remapped, completely changing the hierarchical structure for the local repository as needed.

And unlike Hg, a single Helix local repository may also include content from multiple remote specifications (all of whose content may be re-mapped). But that’s an advanced feature for a future post. It suffices for now that remotes are much more advanced with Helix.


The Hg notion of commit is also quite similar to the Helix submit, with one important difference. Hg users are accustomed to their commits having two separate IDs: (1) a monotonically increasing integer unique and valid only within the scope of the current, local repository, and (2) a forty-character hash value that is both unique and valid in every version of the repository.

In contrast, each Helix changelist, submitted or pending, is identified by a single, monotonically increasing integer number. Many developers won’t care about these details, but DevOps personnel tasked with tying revision IDs to other integrated systems should be aware of them.


There are also minor differences in the naming conventions. Hg users are accustomed to their default path for push and their default branch name both being “default”. In contrast, Helix uses “origin” for its default remote name and “main” for the default branch name. This can be a source of confusion when Hg users first get started and can’t seem to switch back to the “default” branch; just use “main” instead and you’ll be fine.


Having vaulted the conceptual hurdles, let’s look at the commands for the most common tasks. Initializing a new repository requires a “p4 init” rather than an “hg init”, while the usual “hg addremove” followed by “hg commit” is instead “p4 rec” followed by “p4 submit”. All along the way “hg status” is replaced by “p4 status”. Many of the other commands are equally similar. Take a look:


Hg Command

Helix Equivalent

Stage your changes


reconcile (rec for short)

List all branches


switch -l

Branch and switch to it

branch newBranch

switch -c newStream

Create an empty branch

(no equivalent)

switch -cm newStream

Switch to a branch

up branchName

switch streamName

Clone a repository

clone repository

clone -p host:port -r remote

Clone part of a repository

(no equivalent)

clone -p host:port -f fileSpecification[2]

Commit your work



Initialize a repository



Merge work from a branch

merge branchName

merge --from streamName

Get latest updates

pull update[3]

fetch -u -r remoteName -S streamName

Push all local commits



Rewrite history


unsubmit / resubmit[4]

List all remotes



Create a new remote

(no equivalent)[5]

remote newRemoteName

View your changes



As you can see, many of the commands are identical while others are a little different, but those provide what you need to get started. In fact, the above “cheat sheet” nicely serves the majority of day-to-day use cases. In conclusion, Hg users should feel right at home with Helix with very little effort, so why not try the industry’s first DVCS built with the enterprise in mind?


[1] For more information about remote specifications see:

[2] The Helix clone command may be used in a way that Hg cannot: to clone only part of a given shared server, though this has the side effect of bringing it all down in a single branch.

[3] Hg separates the act of pulling new work from updating the local repository for philosophical reasons, so you have to execute its two commands compared to Helix’ fetch command.

[4] For more information about changing local history see:

[5] Hg users have to edit the .hg/.hgrc file manually and add a new entry to the “[paths]” section.

All Perforce Version Management & Collaboration Products Are Free for 20 Users.