How Mercurial Commands and Features Compare to Helix Core
Let’s start with some basics.
Mercurial (Hg) vs. Perforce
Mercurial was developed with a particular eye toward simplifying branching and merging. Helix Core was developed with a more broadly based feature set for a wider variety of workflows/needs. Yet Mercurial and Helix Core actually have more in common than one might otherwise expect.
For starters, work-in-progress is handled similarly by Mercurial and Helix Core. Modifications to versioned files are part of your next commit by default, so the only operations an Mercurial 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 Core reconcile command achieves a similar end result.
The main difference is that while Mercurial includes modifications automatically, Helix Core does not. Helix Core maintains all work-in-progress via a concept known as a changelist, and in particular your work-in-progress is maintained in a changelist named “default”.
Mercurial 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.
Mercurial users have long enjoyed shelving as a feature. Shelving in Helix Core is similar but differs in that Mercurial shelves can be named whereas Helix Core shelves use 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 Mercurial parlance, a “path” is a “pointer” from/to which content may be cloned/pushed, whereas Helix Core users know these as “remote specifications” or just “remotes” for short. Further, a Mercurial “path” offers only a small subset of what Helix Core offers.
A Helix Core remote specification is much more powerful insofar as it includes the ability to map content very selectively. Folders and files may be flexibly remapped, completely changing the hierarchical structure for the local repository as needed.
And unlike mercurial, a single Helix Core depot may also include content from multiple remote specifications (all of whose content may be re-mapped).
The Mercurial notion of commit is also quite similar to the Helix Core submit, with one important difference. Mercurial 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 Core 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. Mercurial users are accustomed to their default path for push and their default branch name both being “default”. In contrast, Helix Core uses “origin” for its default remote name and “main” for the default branch name. This can be a source of confusion when Mercurial users first get started and can’t seem to switch back to the “default” branch; just use “main” instead and you’ll be fine.
Mercurial Commands vs. Helix Core Commands
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:
Helix Core Equivalent
Stage your changes
reconcile (rec for short)
List all branches
Branch and switch to it
switch -c newStream
Create an empty branch
switch -cm newStream
Switch to a branch
Clone a repository
clone -p host:port -r remote
Clone part of a repository
clone -p host:port -f fileSpecification
Commit your work
Initialize a repository
Merge work from a branch
merge --from streamName
Get latest updates
fetch -u -r remoteName -S streamName
Push all local commits
unsubmit / resubmit
List all remotes
Create a new remote
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.
Mercurial users transitioning to Helix Core should feel right at home with very little effort. Not a customer? You can try it free.