Command Secrets Revealed
May 5, 2016

Using P4 Aliases With Helix Core

Version Control

Aliases allow you to a replace a word with another word or string. You can use the alias feature to abbreviate a command or add default arguments to a command you use often. 

Did you know that the Helix Core has always had aliases? If you type p4 workspaces at your command prompt, you will find that this command does the same thing as p4 clients.

The same is also true for the commands p4 password (p4 passwd), and my favorites p4 rec (p4 reconcile) and p4 clean (p4 reconcile –w). These aliases are defined by the server, which calls them synonyms, and they are rarely updated.

In the past, if you wanted to define your own aliases you would either have had to use the REWRITE option of the P4Broker or write a script, losing the benefit of the simple P4 command. Not anymore! In Helix Core you can define your own aliases in your local environment.

Before I go into the details of what exactly you can do with aliases, let me explain the setup and reporting.


P4ALIASES and the .p4aliases File

The default name and location for the aliases configuration file is .p4aliases and resides in your home directory. It is a simple text file of the form “alias = transformation.” You can create additional custom alias files, but you must “point” to them using the P4ALIASES environment variable to make them active. This will use the alias file located wherever your P4CONFIG file resides, typically your workspace root. This format allows you to have different aliases for each workspace, if you so choose.

To point to your environment:

export P4ALIASES=~/.my-other-p4aliases


To add to aliases your P4CONFIG file:




Alias Reporting

Right now, you don’t have any aliases defined. Let’s change that and create an alias file in our home directory. Then we can explore the magic of aliases.

To create an alias file in your home directory:

$ echo "commit = submit" > .p4aliases


Tip for those users who migrated from Subversion, Mercurial, or Git to Perforce. Invoke commit as an alias for the submit command:

$ p4 commit


To see which real command will be used, run:

     $ p4 –aliases=dry-run commit

p4 submit


Simple Command Synonyms

The easiest application of aliases is a simple synonym for another command, like the ones already defined by the server. This can include additional parameters, such as blame = annotate -u.

Any additional parameters and file arguments passed to this new p4 blame are simply added to the resulting p4 annotate command.


Formatted Output

The output of P4 can be modified by using tagged mode and formatting. Tagged mode tells the server to return any date in key/value pairs, and the formatted output makes use of this information.

To enable tagged output, run a P4 command, with the option -ztag:

     p4 –ztag changes –m1

... change 1471

... time 1461319056

... user Aruna_Gupta

... client sknop.main

... status submitted

... changeType restricted

... path //depot/tests/...

... desc A simple change


To format the output, use the –F option to specify the template:

     p4 -ztag -F "Change: %change% Description: %desc%" changes -m1
Change: 1471 Description: A simple change The format can use the keys in the tagged output surrounded by the percent sign.


Typing this sequence every time gets tedious, of course, so we define an alias:

chg = -F "Change: %change% Description: %desc%" –ztag changes


Exploring Parameters

What if we want to refer to a parameter several times or change the order? Then we can use named parameters in the form $(parameter) with recent-changes $(max) = changes -m $(max).

To change the order of the parameters, for example, with the p4 clone command:

       original-clone = clone
       clone $(p4port) $(path) $(dir) = -d $(dir) -u sknop clone -p $(p4port) -f $(path)


Now I can clone with the following command:

p4 clone perforce:1666 //path/to/project/... ~/local-repos/project


Chaining Commands

Things get really interesting when you start chaining commands together using the && operator.

Use both parameters and chaining to create a convenient new command:

delete-shelve $(cl) = shelve –d –c $(cl) && change –d $(cl)


Command Input and Output

Sometimes we would like to use the output of one command in another command. We can do this by redirecting the output into a temporary variable and then read from the same variable again, using the redirect operators < and >.

Keep in mind that the output of the first command is kept in memory in its entirety, and then passed on to the next command. This is not a pipe. If you list every single file on your server and redirect it to a local variable, for example, you might blow the memory of your local machine!

To create a streams depot in a single command, we could create the following alias:

       new-stream-depot $(dpt) = depot -o -t stream $(dpt) > $(spec) &&
                                              depot -i < $(spec)


Parameter substitution

Using the helper command p4subst, we can rewrite the output of one command on the fly and provide it as output into another command. In the new-stream-depot alias above we did not specify the stream depth (a feature added in 2015.2).

So, we need to pass the additional parameter $(depth) that we use to replace the default stream depth, save the spec in a variable and pass it to p4subst. Creating a command that takes two values (a regular expression and a literal value) replaces any instances of the regular expression in the input. This is even more useful because it expands my parameters first.

An example makes this easier to understand.

        new-streamdepth-depot $(dpt) $(depth) = depot -o -t stream $(dpt) > $(spec) &&
                          p4subst "//$(dpt)/1" "//$(dpt)/$(depth)" < $(spec) > $(spec2) &&
                          depot -i < $(spec2)


Then, save the spec in a variable and pass it on to p4subst:

p4subst "regular expression" "literal" < input > output


You can use this alias in the following way:

p4 new-streamdepth-depot newname 1/2/3


Or, even better:

p4 new-streamdepth-depot newname project/component/codeline/pre>


Alias Examples

Here are some more examples I found in our internal promotion wiki for the new alias feature.

To Avoid Typing Long Words

   itg = integrate

   pop = populate

   rc = reconcile

   di = diff


To Use Git or SVN Commands

checkout = sync
commit = submit
purge = clean
stash = shelve
blame = annotate
stash-list = changes -s shelved
pull = fetch –t -r origin


To Alias Your Own Aliases

co = checkout
ci = commit

You can see more examples in the workspace. If you’re looking for more tips, you’ll enjoy these blogs:

Happy hacking!