Introduction

This book contains reference material for Perforce users and administrators. This section provides information about topics that might be useful to you no matter which command or variable you’re interested in. It contains the following subsections:

Getting help for commands and environment variables
Defining command aliases
Naming conventions
Creating scripts

Getting help

In addition to the material provided in this manual, you can get help for Perforce commands by using the p4 help command, which provides help for individual commands or for areas of interest like jobs, revisions, or file types.

The output to the p4 help command as well as the syntax diagrams included in this manual show the short form of Perforce command options. You can also specify command options using long-form syntax. For example, instead of the following command format:

$ p4 reopen -c 1602 -t text+F //depot/my/file

You can now use this format:

$ p4 reopen --change 1602 --filetype text+F //depot/my/file

Note that long-form option names are preceded by two hyphens rather than the usual single hyphen.

The effect of the command is the same whether you use short options names or long option names. Options that are rarely used have only a short form.

To display long-form option syntax for a particular command, use the --explain option; for example:

$ p4 reopen --explain

This will generate output like the following:

--omit-moved (-1): disables following renames resulting from 'p4 move'
--filetype (-t): specifies the filetype to be used.
--change (-c): specifies the changelist to use for the command.
Usage: reopen [-c changelist#] [-t type] files...

To display information about a single option for a command, specify the option name with --explain; for example:

$ p4 revert --explain -k

Command aliases

A small set of Perforce commands have predefined aliases: for example, you can use p4 integ for p4 integrate, or you can use p4 changes for p4 changelists. You can also define your own aliases for commands, and these can range from simple word substitutions to what might be called light scripting.

There are many reasons for creating command aliases: you want to use commands in a language other than English, you want to use commands that are familiar to you from other version control systems, you want to use different defaults, you want to streamline system administration, or you want to use different output formats.

This section covers the following topics:

The process of creating an alias
Basic syntax of alias definitions
Simple and complex alias definitions
How you put it all together
Advanced topics
Limitations

Command aliases may only be used by command line clients; aliases do not work with the derived clients, APIs, or GUIs. Because aliasing is a client-side feature, you can use a command alias with any server, proxy, broker, or replica configuration. However, the particular commands you can run still depend on the server to which you are issuing the commands.

Defining aliases

Command aliases are defined in an alias file. To define one or more aliases, you do the following:

Create a file named .p4aliases in your home directory (p4aliases.txt in Windows).

(The file is stored in your $HOME directory on Unix and Mac systems, and in your $USERPROFILE directory on Windows.)

If you do not put the alias file in the home directory, you must define the P4ALIASES environment variable to specify the location of the alias file.
Add one or more alias definitions to the alias file.

Refer to the following sections for information about the syntax of alias definitions and for examples of alias definitions.
- The file may contain blank lines; they will be ignored.
- The file may also contain comments: the first non-blank character in a comment line must be the # character.
  
  You can edit this file as often as you like to add, modify, or delete definitions.
Preview the effect of the aliases you have defined by running a command like the following for a given command alias:
```
$ p4 --aliases=dry-run myalias
```
The output to the alias command will show you the command or commands that would be run without actually running the command. For more information, see Previewing alias substitutions.
Run the command alias to execute the command or commands associated with the alias.

The server processes command aliases in the order they have been defined, going through each one until it finds one that modifies the current command. It then restarts from the beginning, rechecking each alias. This means that a given command might be transformed more than once before it is run, depending on the aliases that use the command.

Use the p4 aliases command to get a listing of all currently defined aliases.

Command alias syntax

The definition of a command alias can be quite complex. This section describes the basic syntax for defining a command alias and introduces the elements that you can use in a definition; the sections that follow provide a host of examples to illustrate how you can define increasingly complex aliases.

In its simplest form, the syntax for a command alias definition looks like this:

alias = transformation

For example, you want to use French for a command name:

fiches = files

Having included this definition in your alias file, you can now execute a command like p4 fiches @2015/3/15, and have the server list information about all file revisions in the depot as of March 15, 2015.

The alias may use arguments. In this case, the alias arguments are matched against the values the user provides in the transformation. The arguments in the transformation do not have to occur in the same order as they are shown in the alias. They are matched by name. Syntax for this definition looks like this:

alias-name [[$(arg1)...[$(argn)]]= transformation

Syntax for the transformation can vary widely; here’s one possibility:

command $(arg2) $(arg3) $(arg1)

For example:

recent-changes $(max) = changes -m $(max)

The recent-changes alias might then be called as follows:

$ p4 recent-changes 5

And the command would show the last five submitted changelists.

Alias definitions may contain the following elements:

command arguments
environment variables

These include the all Perforce environment variables (for example, P4USER, P4CLIENT, P4PORT) as well as OS variables.
input/output redirection
special operators

The following table describes the special operators that you may use in command alias definitions:

Operator	Meaning
`$(arg)`	Specifies an alias argument in the alias and is matched with arguments in the transformation.
`#`	As the first non-blank character of a line, indicates a comment.
`&&`	Chain commands. See Limitations for information about chaining commands.
`\`	Continue line (use to break up long lines when there are no new commands).
`<`	Take input from.
`>`	Send output to.
`$(EQ)`	Equal to.
`$(LT)`	Less than.
`$(GT)`	Greater than.
`p4subst`	String substitution, for example in editing specs; for more information, see Editing specifications

Because it is hard to include these elements in a syntax definition, their use is illustrated in the next sections, which provide simple and complex sample alias definitions. Reading these sections will help you learn how to define command aliases and how to use these operators.

Basic examples

This section provides examples of simple command alias definitions and illustrates the many uses for even the simplest definitions.

Help me remember who I am.
```
me = set P4USER
```

Help me feel more comfortable as a user of another source control system.

checkout = sync
commit = submit
purge = clean
stash = shelve
stash-list = changes -s shelved

Create a personalized status command that also shows files that need syncing.
```
my-status = status && sync -n
```

Set different defaults.

annotate = annotate -u
grep = grep -i
changes = changes -u $(P4USER)

Simplify system administration.

Shutting down the server, displaying active users:

halt = admin shutdown
active-users = changes -m 3 &&
               monitor show &&
               lockstat

Remembering to clean up empty changelists

kill-shelf $(cl) = shelve -d -c $(cl) &&
                   change -d $(cl)

Change the order of arguments.

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

Now the following command does what you want:

clone perforce:1666 //depot/main/p4...  ~/local-repos/main

Complex examples

More complex alias commands can be formed using redirection and special operators.

Cherry picking.

This alias definition:

cherry-pick-change $(cl) $(s) $(t) = integrate //depot/$(s)/...@$(cl),$(cl) //depot/$(t)/...

Turns this command:

$ p4 cherry-pick-change 1015978 p15.2 main

Into this:

$ p4 integrate //depot/p15.2/...@1015978,1015978          //depot/main/...

Here is another cherry picking example that creates a little merge script:

cherry-pick $(cl) $(s) $(t) $(msg) = \
               integrate //depot/$(s)/...@$(cl),$(cl) //depot/$(t)/... &&
               resolve -am -Ac //depot/$(t)/... &&
               submit -d $(msg) &&
               sync

You could then execute a command like the following:

$ p4 cherry-pick 1015978 two one "line a merged into one"

This would run the following commands:

p4 integrate //depot/two/...@1015978,1015978 //depot/one/...
p4 resolve -am -Ac //depot/one/...
p4 submit -d "Cherry-pick change https://swarm.perforce.com/@1015978[1015978]
              from //depot/two/... to //depot/one/..."
p4 sync

Simple pipelining.

Starting with a simple example:

newStreamsDepot $(dpt) = depot -o -t stream $(dpt) > $(depotSpec) &&
                         depot -i < $(depotSpec)

Note that when using redirection, the $ variables used in the transformation side of the definition, do not need to correspond to the arguments specified one the left side of the equation. In the example above, depotSpec is a variable created during the execution of the newStreamDepot alias.

Here are a couple of aliases for merge down copy up:

mergedown $(b) = fetch &&
                 switch $(b) &&
                 merge &&
                 resolve -am &&
                 submit -d "Merged down from main"

copyup $(b)    = switch dev &&
                 merge --from $(b) &&
                 resolve -as &&
                 submit -d "Copied up from $(b)" &&
                 push

# Note the use of the branch name in the submit message of the copyup alias.

DVCS: Aliases to communicate with multiple servers.

Use aliases like the following when copying spec objects from the shared server to your personal server.

copy-user $(p4port) = -p $(p4port) user -o $(u) > $(spec) &&
                    user -i < $(spec)

copy-job $(p4port) $(j) = -p $(p4port) job -o $(j) > $(spec)  &&
                    job -i < $(spec)

copy-stream $(p4port) $(s)  = -p $(p4port) stream -o $(s) > $(spec) &&
                    stream -i < $(spec)

Putting it all together

Combining the various elements shown so far allows you to build interesting aliases.

Make a new task stream.

If your streams are stored in the depot named //stream, here’s how you would make a new task stream:

newTaskStream $(task) $(parent) = stream -o -t task -P //stream/$(parent) \
                            //stream/$task) > $(streamSpec) &&
                            stream -i < $(streamSpec) &&
                            populate -r -S //stream/$(task) &&
                            client -s -S //stream/$(task) &&
                            sync

Then switching to a new stream becomes very simple; for example:

$ p4 newTaskStream job084103 bp-dev

Delete a stream.

nuke-stream $(branch) = stream -d //stream/$(branch) &&
                        obliterate -y //stream/$(branch)...

Making an alias of an alias,

checkout = sync
commit = submit

co  = checkout
cmt = commit

Previewing alias substitutions

Use the client-side command option --aliases=dry-run to display the command or commands that would have run without actually running them.

For example, if your alias file contains the following:

nuke-stream $(branch) = stream -d //stream/$(branch) &&
                        obliterate -y //stream/$(branch)...

And you execute the following command:

$ p4 --aliases=dry-run nuke-stream test1

The command would return:

p4 stream -d //stream/test1
p4 obliterate -y //stream/test1

Advanced topics

This section describes more advanced uses of command aliases.

Editing specifications

The p4subst special operator allows you to edit specs. It is roughly analogous to doing the following in a shell pipeline:

| sed 's/regular_expression/literal/g'

The p4subst special operator should normally be used in an alias as fellows:

something > $(output) &&
p4subst "regular expression" "literal replacement" < $(output) > $(result) &&
something else < $(result)

As an example, consider the string substitution in the following alias:

newChange $(desc) = change -o > $(chg) &&
                   p4subst "$(LT)enter.*$(GT)" $(desc) < $(chg) > $(chg2) &&
                   change -i < $(chg2)

The alias replaces the default change description with the argument provided to p4 newChange description.

Creating alias files for each workspace

To create an alias file for each workspace, add the following line to your P4CONFIG file:

P4ALIASES=$configdir/p4aliases.txt

Since your P4CONFIG file is found wherever you might be working and that location is known by the special $configdir value, you can have a P4ALIASES file that is specific to this workspace and which is conveniently found no matter where you are in that workspace.

Limitations

Aliases can be very powerful. Be mindful of consequences:

Multi-command chains in an alias are different than shell pipelines. Each sub-command in a shell pipeline is started by the shell as a separate child process, and their input and output is connected using operating system constructs. A multi-command alias, on the other hand, executes in the context of a top-level p4 process, and it executes each sub-command serially, inside the parent p4 process, storing the output in memory. This limits the amount of data that can be piped from one command to the next.
If one chained command fails, no subsequent commands are executed.

Naming conventions

Perforce enforces only a few rules related to what you name Perforce objects:

Clients, depots, labels, and branches may not have the same name.
The following names are reserved and may not be used to name anything: head,have, none.

Otherwise, naming conventions are limited to best practices; the guiding principles being to use names that help you guess what the content is, to use consistent naming schemes, and to choose names that are likely to group like objects in alphabetical listings.

The following table provides some suggestions that are specific to Perforce objects:

Object	Naming convention
branches	Best to name them.
clients	The following scheme is commonly used, but not enforced in any way. Use it if it suits your purpose. user.machineTag.product user.machineTag.product.branch user is the OS user; machineTag is the host name or something that describes the host; for example `Win7VM` or `P4MBPro` (for Perforce MacBook Pro). Whether you use product or product.branch depends on whether your workspace gets re-purposed from stream to stream (in which case just use product), or you have multiple workspaces, one for each branch (in which case use product.branch, effectively tying the workspace name to the branch).
depots	Best to keep the names short. Depot names are part of an organization hierarchy for all your digital assets, so naming them and planning directory structure is especially important.
jobs	Name jobs to match your external defect tracker issues: for example, `PRJ-1234` for JIRA issues.
labels	Label names are site-dependent and might vary with code management schemes and versioning needs. For example `R-3.2.0` might refer to release 3.2.0.

Creating scripts

In addition to chaining commands in an alias to create a light script, you can combine the commands described in this manual in scripts. Perforce works with Triggers, user-written scripts called by a Perforce server whenever certain operations occur. Such operations include changelist submissions changes to forms, login attempts, and so on.

For more information about writing scripts, see the Helix Versioning Engine Administrator Guide: Fundamentals.

P4 Command Reference (2016.1)