NAME

a4 - Access the Perforce SCM system following certain conventions

SYNOPSIS

a4 -chpPuqv subcommand [opts] [args]

a4 -V|--version

a4 (--help[=topic] | --plain-help[=topic] | --pod-help[=topic])

DESCRIPTION

a4 is the command-line interface to the A4 source configuration management system. A4 builds upon p4(1) by setting certain conventions and adding certain capabilities. See a4intro(1).

On-line help is available. See SubCommand/HELP.

OPTIONS

The following options are accepted (before the subcommand, if any):

-P --passwd host
Specify the p4 user password

-V --version
Print the a4 version number and exit.

-c --client client
Specify the p4 client name

-h --host host
Specify the p4 client host

-p --port host:port
Specify the p4 server port

-q --quiet --noq
Suppress warnings and p4 result counts

-u --user host
Specify the p4 client user

-v --verbose --nov
Print p4 commands and results. Results are suppressed if -q is in effect. By default, only a result count is printed, which is usually what you want because most subcommands operate on the entire workspace, so results tend to scroll off the screen en masse.

--help [topic]
Print help for this command, or for the given topic.

--plain-help [topic]
Print plain-text help for this command, or for the given topic.

--pod-help [topic]
Print POD help for this command, or for the given topic.

See OPTIONS PARSING in the SubCommand::Usage manpage for option parsing rules.

SUBCOMMANDS

applypatch -fdt

Read a patch file (usually generated by a4 createpatch) from STDIN, and apply the patch to the current client.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-d --mix --nod
Permits patch records to take precedence over the target client file in cases that would normally conflict, such as adding an already existing file or deleting a file already open for edit. Also, any integrations are applied with -d.

-f --force --remerge --nof
Integrations from the patch are applied with -f and resolved with -ay. By default, integrations are left for the use to resolve later.

-t --type --uptype --not
The type of each patched file is updated to match the type indicated in the patch (unless the file isn't open and isn't in the depot).

branch -gm [branch]

The codeline's properties are set according to the specified options. A property is not cleared unless its option is sepcified in the negative.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-g --gated --nog
Codeline is gated with a regression.

-m --merging --nom
Codeline is designated fully merging with its parent.

client -hpr [client]

The workspace's properties are set according to the specified options. A property is not cleared unless its option is sepcified in the negative.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-h --keep-host --noh
Restrict use of the client to the current host.

-p --keep-port --nop
The client's .p4env specifies the p4 server port.

-r --alt-roots --nor
Update the client's AltRoots: property.

clone [(-p|--prefix) path] [change-number]

The reference build given by the branch of the current client and change-number is copied directly into the current client, generated files and all. ``p4 flush'' is used to make sure that the Perforce database reflects the client's contents.

change-number defaults to the greatest change number for which there is an existing (successfully completed) reference build of the client's branch.

This operation will fail without side-effects if any files already opened in the client would be overwritten.

The prefiles and postfiles files for the current branch in the CFG subtree are renamed to prefiles.bak and postfile.bak, respectively, such that the client view matches the view of the reference build. If desired, you may rename them back and regenerate the view using a4 sync.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-p --prefix path
Use the given path as the prefix directory for reference builds. It may or may not have a sensible default, depending on the current value of the A4PLATFORM environment variable and the way A4 was configured.

copying

Prints the A4 distribution restrictions (that is, the relevant sections of the GPL).

createpatch [-i] [arg] ...

Print a patch file representing the unsubmitted changes to the current client to STDOUT.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-i --integ --integrate --noi
Include files open for integrate in the patch. By default, they are ignored with a warning, because it's dangerous to reroute the integration path.

help subcommand topic

help [topic]

print help for topic

integrate [-o] [arg] ...

Does basically the same thing as p4 integrate, except that the -b option is filled in automatically, and the integration view is used by default. Additional options and arguments are passed along to p4 integrate.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-o --orig --original --noo
Use the current client view instead of the integration view.

maketree [-l] [-creldir|-dsubdir] [client]

Each directory in the current workspace is populated with a .p4top symbolic link to the root of the workspace. A .p4env file is created at the top of the workspace, and in every directory containing a .p4props file.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-c --reldir reldir
Operate only on the subtree whose root is given by the specified directory relative to the current working directory.

-d --dir --directory --subdir subdir
Operate only on the subtree whose root is given by the specified directory relative to the client root.

-l --local --single
Operate only on the directory specified with -c or -d, or only in the root directory if no directory is specified.

merge [-s] branch

If the specified child branch is designated fully-merging and contains all of the changes in the current client's branch (the parent branch), then clone the child branch into the parent branch using p4 integrate -fdt and p4 resolve -at.

If the -s option is specified and the branch is gated, then the operation is atomic, meaning that no other submission to the parent branch can sneak in once the submit lock is obtained.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-s --submit --nos
Lock the parent branch before integrating, and submit the result atomically. A simple change list description is generated automatically.

newbranch [-m] [-ldepot-location] parent [branch]

A new branch is created according to the conventions of A4. The branch argument may include the # and @ wildcards.

You need to do an explicit a4 integrate afterwards in order to populate the branch with its parent's files.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-l --loc --location depot-location
Specify a depot location for the codeline.

-m --merging --nom
Codeline is designated fully merging with its parent. Default is set.

newclient -hps [-n|-N] [-vview] branch [client]

A new client is created according to the conventions of A4. The branch argument may include a revision specifier. The client argument may include the # and @ wildcards.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-N --unconfigured --nounconfigured
Don't sync the workspace, not even the configuration.

-h --keep-host --noh
Restrict use of the client to the current host.

-n --unsynced --non
Sync the configuration, but not the rest of the workspace.

-p --keep-port --nop
The client's .p4env specifies the p4 server port.

-s --snap --snapshot --nos
Run in snapshot mode. Always completes in a single pass, but the result might already be out-of-date when it's done.

-v --vname --viewname view
Use the given view as a suffix for prefiles-* and postfiles-* in the configuration directory. If either is found, then prefiles and postfiles, respectively, are replaced with symbolic links to them. Otherwise, no special action is taken, but an error results.

nonsource [-a] [pattern] ...

Any files found in the current workspace matching any of the specified patterns (in Perforce local syntax) that are not in the ``have'' or ``opened'' list are printed to STDOUT. If no patterns are specified, then the entire workspace is checked.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-a --all --noa
Report files even if they aren't in the current view.

plain-help subcommand topic

plain-help [topic]

print help in plain text for topic

pod-help subcommand topic

pod-help [topic]

print help in POD for topic

presub [change]

Check that the workspace associated with the specified change passes its presubmit regression, even if it's not on a gated branch. The correct client must be specified via the -c top-level option if it's not the current client.

On-line help is available. See SubCommand/HELP.

receive -ifdt client

A patch is generated based on the unsubmitted changed to the specified client (which must not be the same as the current client), and that patch is applied to the current client.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-d --mix --nod
Permits patch records to take precedence over the target client file in cases that would normally conflict, such as adding an already existing file or deleting a file already open for edit. Also, any integrations are applied with -d.

-f --force --remerge --nof
Integrations from the patch are applied with -f and resolved with -ay. By default, integrations are left for the use to resolve later.

-i --integ --integrate --noi
Include files open for integrate in the patch. By default, they are ignored with a warning, because it's dangerous to reroute the integration path.

-t --type --uptype --not
The type of each patched file is updated to match the type indicated in the patch (unless the file isn't open and isn't in the depot).

refbuild [(-p|--prefix) path] branch

Create a new reference build based on branch, which may include a change number specification.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-p --prefix path
Use the given path as the prefix directory for reference builds. It may or may not have a sensible default, depending on the current value of the A4PLATFORM environment variable and the way A4 was configured.

regr [level]

Check that the workspace passes its content regression, even if it's not a gated branch. The level argument defaults to 1.

On-line help is available. See SubCommand/HELP.

rmbranch [-y] branch

If no clients or other branches depend on the named branch, then remove its record form the Perforce database. The branch record is automatically unlocked if it is initially locked.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-y --obliterate --noy
Purge all the revisions from the depot before removing the branch record. This saves disk space if you're never going to refer back to the codeline, but it's irreversible.

rmclient [-f] client

The entire workspace directory removed, and if successful, the client record is deleted. The client record is automatically unlocked if it is initially locked.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-f --force --nof
Revert any files opened on the client before proceeding. By default, the command will fail if any opened files are detected.

setup

A SUID script is created in the .a4 subdirectory of the user's home directory to allow the Perforce server to initiate a presubmit regression.

On-line help is available. See SubCommand/HELP.

submit [(-c|--change) change-num] [arg] ...

Attempt to obtain the submit lock for the client's branch, and (if successful) run p4 submit with the arguments. The lock is released automatically.

If a change list is specified, then the client must match the client of the change list, or else you will attempt to obtain the wrong lock, and the A4 submit trigger will fail if it is enabled.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-c --change change-num
Specify a numbered changelist (mandatory).

sync -afs [(-v|--vname|--viewname) view] [client]

The client's configuration is sync'ed, the view is rebuilt according to the updated configuration if any files were updated or -f is specified, and the entire workspace is sync'ed. a4 maketree is also run if any files were updated or -f is specified. client may contain a revision specifier.

The exit status is 0 for no files updated, or 1 for at least one file updated.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-a --all --integrate --noa
Use the integration view instead of the default view

-f --force --nof
Force the configuration to be re-made and maketree to be run

-s --snap --snapshot --nos
Run in snapshot mode. Always completes in a single pass, but the result might already be out-of-date when it's done.

-v --vname --viewname view
Use the given view as a suffix for prefiles-* and postfiles-* in the configuration directory. If either is found, then prefiles and postfiles, respectively, are replaced with symbolic links to them. Otherwise, no special action is taken, but an error results.

syncview -af [(-v|--vname|--viewname) view] [client]

The client's configuration is sync'ed, and the view is rebuilt according to the updated configuration if any files were updated or -f is specified. client may contain a revision specifier.

The exit status is 0 for no files updated, or 1 for at least one file updated.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-a --all --integrate --noa
Use the integration view instead of the default view

-f --force --nof
Force the configuration to be re-made

-v --vname --viewname view
Use the given view as a suffix for prefiles-* and postfiles-* in the configuration directory. If either is found, then prefiles and postfiles, respectively, are replaced with symbolic links to them. Otherwise, no special action is taken, but an error results.

top [-c] [client]

The client's root directory is printed to STDOUT.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-c --cfg --config --noc
Instead of the client's root directory, print its CFG subdirectory corresponding to its branch.

upview [-a] [(-v|--vname|--viewname) view] [client]

The client's view is rebuilt according to the current contents of the configuration directory.

On-line help is available. See SubCommand/HELP.

The following options are accepted:

-a --all --integrate --noa
Use the integration view instead of the default view

-v --vname --viewname view
Use the given view as a suffix for prefiles-* and postfiles-* in the configuration directory. If either is found, then prefiles and postfiles, respectively, are replaced with symbolic links to them. Otherwise, no special action is taken, but an error results.

warranty

Prints the A4 warranty (that is, the relevant sections of the GPL).

SEE ALSO

a4intro(1), the A4::Ops manpage

ENVIRONMENT

The environment variables used by p4 will (as a rule) affect a4 in the same way. In addition, the following environment variables are used:

A4EXPERT
If set, suppress the printing of usage information when a command line fails to parse.

A4PLATFORM
The name of the current platform, for determining where the reference builds live. Defaults to $^O, but you should avoid using this default for branches that generate machine code, because the wrong thing will happen if you use it, for example, on a machine of the same OS that has a different processor.

A4_ALT_ROOTS
A space-delimited set of directory mappings for setting the ``AltRoots:'' property on clients. Don't define it unless your Perforce server version is 2002.2 or later.

Each mapping consists of the alternate (foreign) directory on the left, followed by =, followed by the primary (local) directory on the right. Both sides should include the trailing directory delimiter. Up to the first two mappings in which the right side prefixes the primary root will be used.

If the matching alternate directory contains any back-slashes (), then any forward slashes (/) in the remaining primary path components will be converted to back-slashes; otherwise, and back-slashes in the remaining path components will be converted to forward slashes.

A4_CLIENT_TEMPLATE
A Perl expression that returns a template for a new client name. It is executed in a Safe with the following variables set: $branch, $user, $port, $host. See Safe.

A4_BRANCH_TEMPLATE
A Perl expression that returns a template for a new branch name. Similar to A4_CLIENT_TEMPLATE, except that $parent is also defined to the same value as $branch.

POSIXLY_CORRECT
Affects various aspects of command line parsing. See the SubCommand::Args manpage, the SubCommand::Usage manpage and the SubCommand::Switch manpage for details.