June 16, 2015

Helix DVCS - How to Initialize Like a Pro



We are all very excited about the new distributed version control system (DVCS) capabilities of Perforce Helix. Here are a few tips for getting started.

Keep in mind that in order to use Helix DVCS, you need to have the 2015.1 version of both Helix client P4 and Helix server P4D installed. Some of the commands (e.g., init and clone) are implemented in P4, so you need the latest version of both executables.

The first thing you need to do when you want to use a local Helix server (called a personal server) is to run “p4 init”.  This command will create the personal server for you (in a subdirectory called .p4root) and set up the P4CONFIG and P4IGNORE files, as well.

“p4 init” also turns your current directory into the client workspace root for your new personal server, which is useful if you already have some files and realize it might be a good thing to version them:

    p4 init
    p4 rec
    p4 submit -n "Initial checkin"

In the above, “rec” is a handy alias for “reconcile” to save you typing.

If you start a new project from scratch and want to place it in another directory instead, use the “-d” option like such:

    p4 –d path-to-new-project init

Case and Unicode

Let’s take a closer look at the output of the “p4 init” command:

    Matching server configuration from ‘wayfarer-p4d:1666':
    case-sensitive (-C0), non-unicode (-n)
    Server sknop-dvcs-1429629213 saved.

One might ask: what is case-sensitive and Unicode about?

Because the Helix versioning engine supports many platforms, both case sensitive and insensitive, you can choose how your personal server handles case. By default, the Helix versioning engine adopts the case policy of the platform you run it on: insensitive on Mac and Windows, sensitive on Linux and other Unix platforms.

Also by default, the Helix versioning engine does no Unicode translation and simply accepts any encoding for file content and metadata. For cross-platform development it is better to put a shared server into Unicode mode.

For a personal server you may not care at first what these settings are, but what if you want to push your changes to another server at a later stage? The settings of your personal server have to match the settings on the destination server or there could be chaos, as the destination server will refuse the push if the settings do not match.

It is cumbersome to change case sensitivity and Unicode settings after the Helix versioning engine is populated, so it is important to get this right up front. “p4 init” will “guess” what the standard settings within your enterprise are by connecting to and inquiring with the Helix versioning engine specified by the P4PORT environment variable (or “perforce:1666” if that is not set).

If you’d rather inquire with a particular server when initializing a personal server, use the “-p” option:

    p4 init –p myserver:1666

Alternately, you can also explicitly set case and Unicode support with the following options:

-C1Case insensitive
-C0Case sensitive
-nNo Unicode support
-xiUnicode support

Server and User NameNote well: if you have P4CHARSET defined in your environment and not set to “none”, a new personal server will automatically be initialized as a Unicode-enabled server.

So what is the story with the server and user name?

The name of your personal server and client workspace coincide. Although in principle you can have more than one workspace against your personal server, in practice there is rarely any need for it. Locally the name does not matter, but when you push your changes into another server, the changes are linked to your local workspace name. An automatically generated name like “sknop-dvcs-1429629213” is highly likely do be unique, but you are free to choose a different name if you so wish by using the “-c” option.

The same is true for your user name: locally it does not matter and will typically coincide with either your OS user name and/or whatever P4USER is set to, but when pushing to another server the user name becomes important.

Take the Perforce workshop for example: my local user name is always “sknop”, but for the workshop I use “sven_erik_knop”. If I create a local DVCS server under the user name “sknop”, submit my changes, set up a remote to the workshop, and push, I’ll receive only an error message.

Fortunately, the solution is very simple. I add another user to my local server and update my local protection table:

    p4 user –f sven_erik_knop
    p4 protect

Now I can push my changes under the new user name (I might have to log into the target server first):

    p4 –u sven_erik_knop push


A simple “p4 init” will create you a new personal server to which you can submit changes, but if you want to push these changes to another server, it makes sense to pay attention to case sensitivity, Unicode support, and workspace and user name.

Let me know if you are using our new DVCS features and how you are getting on. My Twitter handle is @p4sven.

For a live technical overview of DVCS features in the Helix Versioning engine sign up for our DevTalk Webinar on June 26th.