May 21, 2015

Helix Versioning Engine for Git Users

Git at Scale

The new DVCS features of Perforce Helix are easy to use, but making the transition from another system always involves climbing a learning curve. Toward that end, it only makes sense to provide some guidance toward the summit. The purpose of this post is to do that specifically for Git users.


Let’s begin with some basics. Git 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, and as such it’s important to explain some Helix concepts in terms familiar to a Git user.


The Git index or staging area is actually a single file,[1] which contains only the changes to be recorded by the next commit. It’s also pretty unique insofar as it allows savvy users to stage a one-line change while leaving other changes to the same file un-staged. But the important part for our purposes is that the index or staging area is where you specify what you want to commit.

Helix has a concept known as a changelist instead, which similarly specifies what you want to submit. Each changelist also has a unique integer number, description, and other useful properties, but most importantly they track work in progress. Git users largely don’t need to worry as work is automatically put into a default changelist by the reconcile command, ready to submit whenever you are.


Another popular Git feature is the ability to stash work and recall it later. The Git stash is actually a last-in-first-out (LIFO) queue to which users may push multiple units of work and flexibly pop them later. Helix instead supplies the ability to shelve work in progress, which is not a queue but rather a feature of a changelist. Unlike the stash, the default changelist has a single shelf where work in progress may be safely kept when switching branches or what not.


Git remotes are mere “pointers” from/to which content may be cloned/pushed, which is only a small subset of what Helix offers. A Helix remote specification is far more powerful insofar as it includes the ability to map content very selectively.[2] Folders and files may be flexibly remapped, completely changing the hierarchical structure for the local repository as needed.

And unlike Git, 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 Git notion of commit is almost identical to the Helix submit, with at least one very important difference. While Git commit IDs are ugly, forty-character hash values (as I’ve blogged previously) each Helix changelist submitted results in a simple, monotonically increasing integer number that’s much easier to work with. Many developers won’t care, but DevOps personnel tasked with tying revision IDs to other integrated systems should be aware of it.


There is also a minor difference in the default naming conventions. To wit, Git and Helix both use “origin” for the default remote name, but whereas Git uses “master” for the default branch Helix uses “main” instead. This can be a source of confusion when Git users first get started and can’t seem to switch back to the “master” 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 a “git init”, while the usual “git add” followed by “git commit” is instead “p4 rec” followed by “p4 submit”. And all along the way “git status” is replaced by “p4 status”. Many of the other commands are equally similar. Take a look:


Git Command

Helix Equivalent

Stage your changes


reconcile (rec for short)

List all branches


switch -l

Branch and switch to it

branch -b newBranch

switch -c newStream

Create an empty branch

checkout --orphan newBranch

switch -cm newStream

Switch to a branch

checkout 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[3]

Commit your work



Initialize a repository



Merge work from a branch

merge branchName

merge --from streamName

Get latest updates


fetch -u -r remoteName -S streamName

Push all local commits

push --all


Rewrite history


unsubmit / resubmit[4]

List all remotes



Create a new remote

remote add newRemoteName repository

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, Git 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 the basics of the index/staging see:

[2] For more information about remote specifications see:

[3] The Helix clone command may be used in a way that Git 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.

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


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