Global Options

Synopsis

Global options for Perforce commands; these options can be supplied on the command line before any Perforce command.

Syntax


p4 [-bbatchsize -cclient -ddir -Hhost -pport -Ppass -uuser -xfile -Ccharset
    -Qcharset -Llanguage] [-I] [-G] [-s] [-z tag] cmd [args ...]

p4 -V
p4 -h

Options

-b batchsize

Specifies a batch size (number of arguments) to use when processing a command from a file with the -x argfile option. By default, the batch size is 128.

-c client

Overrides any P4CLIENT setting with the specified client name.

-d dir

Overrides any PWD setting (current working directory) and replaces it with the specified directory.

-I

Specify that progress indicators, if available, are desired. This option is not compatible with the -s and -G options.

-G

Causes all output (and batch input for form commands with -i) to be formatted as marshalled Python dictionary objects. This is most often used when scripting.

-H host

Overrides any P4HOST setting and replaces it with the specified hostname.

-p port

Overrides any P4PORT setting with the specified protocol:host:port.

-P pass

Overrides any P4PASSWD setting with the specified password.

-r retries

Specifies the number of times to retry a command (notably, p4 sync) if the network times out.

-s

Prepends a descriptive field (for example, text:, info:, error:, exit:) to each line of output produced by a Perforce command. This is most often used when scripting.

-u user

Overrides any P4USER, USER, or USERNAME setting with the specified user name.

-x argfile

Instructs Perforce to read arguments, one per line, from the specified file. If file is a single hyphen (-), then standard input is read.

-C charset

Overrides any P4CHARSET setting with the specified character set.

-Q charset

Overrides any P4COMMANDCHARSET setting with the specified character set.

-L language

This feature is reserved for system integrators.

-z tag

Causes output of many reporting commands to be in the same tagged format as that generated by p4 fstat.

-q

Quiet mode; suppress all informational message and report only warnings or errors.

-V

Displays the version of the p4 application and exits.

-h

Displays basic usage information and exits.

Usage Notes

  • Be aware that the global options must be specified on the command line before the Perforce command. Options specified after the Perforce command will not be interpreted as global options, but as options for the command being invoked. It is therefore possible to have the same command line option appearing twice in the same command, being interpreted differently each time.

    For example, the command p4 -c anotherclient edit -c 140 file.c will open file file.c for edit in pending changelist 140 under client workspace anotherclient.

  • The -x option is useful for automating tedious tasks; a user adding several files at once could create a text file with the names of these files and invoke p4 -x textfile add to add them all at once.

    The -x option can be extremely powerful, as powerful as whatever generates its input. For example, a UNIX developer wishing to edit any file referring to an included file.h file, for instance, could grep -l file.h *.c | cut -f1 -d: | p4 -x - edit.

    In this example, the grep command lists occurrences of file.h in the *.c files, the -l option tells grep to list each file only once, and the cut command splits off the filename from grep's output before passing it to the p4 -x - edit command.

  • The -s option can be useful in automated scripts.

    For example, a script could be written as part of an in-house build process which executes p4 -s commands, discards any output lines beginning with "info:", and alerts the user if any output lines begin with "error:".

  • Python developers will find the -G option extremely useful for scripting. For instance, to get a dictionary of all fields of a job whose ID is known, use the following:

    job_dict = marshal.load(os.popen('p4 -G job -o ' + job_id, 'rb'))

    In some cases, it may not be intuitively obvious what keys are used by the application. If you pipe the output of any p4 -G invocation to the following script, you will see every record printed out in key/value pairs:

    #!/usr/local/bin/python
    
    import marshal, sys
    
    try:
        num=0
        while 1:
            num=num+1
            print '\n--%d--' % num
            dict = marshal.load(sys.stdin, 'rb')
            for key in dict.keys(): print "%s: %s" % (key,dict[key])
    
    except EOFError: pass
    

    Python developers on Windows should be aware of potential CR/LF translation issues; in the example, it is necessary to call marshal.load() to read the data in binary ("rb") mode.

  • At present, the progress indicator requested when you use the -I option is only available with p4 -I submit and p4 -I sync -q.

  • Some uses of the global options are absurd.

    For example, p4 -c workspace help provides exactly the same output as p4 help.

Examples

p4 -p new_service:1234 sync

Performs a sync after connecting to new_service and port 1234, regardless of the settings of the P4PORT environment variable.

p4 -c new_client submit -c 100

The first -c is the global option to specify the client workspace name. The second -c specifies a changelist number.

p4 -s -x filelist.txt edit

If filelist.txt contains a list of files, this command opens each file on the list for editing, and produces output suitable for parsing by scripts.

Any errors as a result of the automated p4 edit commands (for example, a file in filelist.txt not being found) can then be easily detected by examining the command's output for lines beginning with "error:"