Perforce 2008.2 P4 User's Guide
<< Previous Chapter
Defect Tracking
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Glossary

Chapter 8
Scripting and Reporting

This chapter provides details about using p4 commands in scripts and for reporting purposes. For a full description of any particular command, consult the Perforce Command Reference, or issue the p4 help command.

Common flags used in scripting and reporting

The following command-line flags enable you to specify settings on the command line and in scripts. For full details, refer to the description of global options in the Perforce Command Reference.

Flag
Description

-c client_workspace

Specifies the client workspace name.

-G

Causes all output (and batch input for form commands with -i) to be formatted as marshaled Python dictionary objects.

-p server:port

Specifies the host and port number of the Perforce server.

-P password

Specifies the user password if any. If you prefer your script to log in before running commands (instead of specifying the password every time a command is issued), use the p4 login command. For example:

echo 'mypassword' | p4 login

-s

Prepends a descriptive field (for example, text:, info:, error:, exit:) to each line of output produced by a Perforce command.

-u user

Specifies the Perforce user name.

-x argfile

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

Scripting with Perforce forms

If your scripts issue p4 commands that require the user to fill in a form, such as the p4 client and p4 submit commands, use the the -o flag to write the form to standard output and the -i flag to read the edited form from standard input.

For example, to create a job using a script on UNIX:

  1. Issue the p4 job -o > temp1 command to write a blank job specification into a text file.

  2. Make the necessary changes to the job. For example:

  3. Issue the p4 job -i < temp2 command to save the job.

To accomplish the preceding without a temporary file, issue the following command:

p4 job -o | sed 's/<enter description here>/Crash when exiting./' | p4 job -i The commands that display forms are:

File reporting

The following sections describe commands that provide information about file status and location. The following table lists a few basic and highly-useful reporting commands.

To display this information
Use this command

File status, including file type, latest revision number, and other information

p4 files

File revisions from most recent to earliest

p4 filelog

Currently opened files

p4 opened

Preview of p4 sync results

p4 sync -n

Currently synced files

p4 have

The contents of specified files

p4 print

The mapping of files' depot locations to the corresponding workspace locations.

p4 where

A list of files and full details about the files

p4 fstat

Displaying file status

To display information about single revisions of files, issue the p4 files command. This command displays the locations of the files in the depot, the actions (add, edit, delete, and so on) performed on those files at the specified revisions, the changelists in which the specified file revisions were submitted, and the files' types. The following example shows typical output of the p4 files command:

The p4 files command requires one or more filespec arguments. Regardless of whether you use local, client, or depot syntax to specify the filespec arguments, the p4 file command displays results using depot syntax. If you omit the revision number, information for the head revision is displayed. The output of p4 files includes deleted revisions.

The following table lists some common uses of the p4 files command.

To display the status of
Use this command

All files in the depot, regardless of your client workspace view

For depots containing numerous files, you can maximize performance by avoiding commands that refer to the entire depot (//depot/...) when not required. For best performance, specify only the directories and files of interest.

p4 files //depot/...

The files currently synced to the specified client workspace

p4 files @clientname

The files mapped by your client workspace view

p4 files //clientname/...

Specified files in the current working directory

p4 files filespec

A specified file revision

p4 files filespec#rev

Specified files at the time a changelist was submitted, regardless of whether the files were submitted in the changelist

p4 files filespec@changenum

Files tagged with a specified label

p4 files filespec@labelname

Displaying file revision history

To display the revision history of a file, issue the p4 filelog filespec command. The following example shows how p4 filelog displays revision history.

p4 filelog //depot/dev/main/jam/jam.c

//depot/dev/main/jam/jam.c
... #35 change 627 edit on 2001/11/13 by earl@earl-dev-yew (text) 'Handle platform variants better'
... #34 change 598 edit on 2001/10/24 by raj@raj-althea (text) 'Reverse previous attempt at fix'
... ... branch into //depot/release/jam/2.2/src/jam.c#1
... #33 change 581 edit on 2001/10/03 by gale@gale-jam-oak (text) 'Version strings & release notes'

To display the entire description of each changelist, specify the -l flag.

Listing open files

To list the files that are currently opened in a client workspace, issue the p4 opened filespec command. The following line is an example of the output displayed by the p4 opened command:

The following table lists some common uses of the p4 opened command.

To list
Use this command

Opened files in the current workspace

p4 opened

Opened files in all client workspaces

p4 opened -a

Files in a numbered pending changelist

p4 opened -c changelist

Files in the default changelist

p4 opened -c default

Whether a specific file is opened by you

p4 opened filespec

Whether a specific file is opened by anyone

p4 opened -a filespec

Displaying file locations

To display information about the locations of files, use the p4 where, p4 have, and p4 sync -n commands:

You can use these commands with or without filespec arguments.

The following table lists some useful location reporting commands.

To display
Use this command

The revision number of a file that you synced to your workspace

p4 have filespec

How a particular file in the depot maps to your workspace

p4 where //depot/filespec

Displaying file contents

To display the contents of a file in the depot, issue the p4 print filespec command. This command prints the contents of the file to standard output or to a specified output file, with a one-line banner that describes the file. To suppress the banner, specify the -q flag. By default, the head revision is displayed, but you can specify a file revision.

To display the contents of files
Use this command

At the head revision

p4 print filespec

Without the banner

p4 print -q filespec

At a specified changelist number

p4 print filespec@changenum

Displaying annotations (details about changes to file contents)

To find out which file revisions or changelists affected lines in a text file, issue the p4 annotate command.

By default, p4 annotate displays the file line by line, with each line preceded by a revision number indicating the revision that made the change. To display changelist numbers instead of revision numbers, specify the -c flag.

Monitoring changes to files

To track changes to files as they occur, you can use the Perforce change review daemon, which enables Perforce users to specify files and directories of interest and receive email when a changelist that affects the specified files is submitted. For details about administering the review daemon, refer to the Perforce System Administrator's Guide and to the description of the p4 review command in the Perforce Command Reference.

The following table lists commands that display information about the status of files, changelists, and users. These commands are often used in review daemons.

To list
Use this command

The users who review specified files

p4 reviews filespec

The users who review files in a specified changelist

p4 reviews -c changenum

A specified user's email address

p4 users username

Changelist reporting

The p4 changes command lists changelists that meet search criteria, and the p4 describe command lists the files and jobs associated with a specified changelist. These commands are described below.

Listing changelists

To list changelists, issue the p4 changes command. By default, p4 changes displays one line for every changelist known to the system. The following table lists command-line flags that you can use to filter the list.

To list changelists
Use this command

With the first 31 characters of the changelist descriptions

p4 changes

With full descriptions

p4 changes -l

The last n changelists

p4 changes -m n

With a specified status

p4 changes -s pending
or
p4 changes -s submitted

From a specified user

p4 changes -u user

From a specified workspace

p4 changes -c workspace

That affect specified files

p4 changes filespec

That affect specified files, including changelists that affect files that were later integrated with the named files

p4 changes -i filespec

That affect specified files, including only those changelists between revisions m and n of these files

p4 changes filespec#m,#n

That affect specified files at each revision between the revisions specified in labels lab1 and lab2

p4 changes filespec@lab1,@lab2

Submitted between two dates

p4 changes @date1,@date2

Submitted on or after a specified date

p4 changes @date1,@now

Listing files and jobs affected by changelists

To list files and jobs affected by a specified changelist, along with the diffs of the changes, issue the p4 describe command. To suppress display of the diffs (for shorter output), specify the -s flag.

To list
Use this command

Files in a pending changelist

p4 opened -c changenum

Files submitted and jobs fixed by a particular changelist, including diffs

p4 describe changenum

Files submitted and jobs fixed by a particular changelist, suppressing diffs

p4 describe -s changenum

Files and jobs affected by a particular changelist, passing the context diff flag to the underlying diff program

p4 describe -dc changenum

The state of particular files at a particular changelist, regardless of whether these files were affected by the changelist

p4 files filespec@changenum

The following table lists some useful changelist reporting commands.

For more commands that report on jobs, see "Job reporting" on page 99.

Label reporting

To display information about labels, issue the p4 labels command. The following table lists some useful label reporting commands.

To list
Use this command

All labels, with creation date and owner

p4 labels

All labels containing a specific file revision (or range)

p4 labels file#revrange

Files tagged with a specified label

p4 files @labelname

A preview of the results of syncing to a label

p4 sync -n @labelname

Branch and integration reporting

The following table lists commonly used commands for branch and integration reporting.

To list
Use this command

All branch specifications

p4 branches

Files in a specified branch

p4 files filespec

The revisions of a specified file

p4 filelog filespec

The revisions of a specified file, recursively including revisions of the files from which it was branched

p4 filelog -i filespec

A preview of the results of a resolve

p4 resolve [args] -n [filespec]

Files that have been resolved but not yet submitted

p4 resolved [filespec]

Integrated, submitted files that match the filespec arguments

p4 integrated filespec

A preview of the results of an integration

p4 integrate [args] -n [filespec]

Job reporting

Listing jobs

To list jobs, issue the p4 jobs command. The following table lists common job reporting commands.

To list
Use this command

All jobs

p4 jobs

All jobs, including full descriptions

p4 jobs -l

Jobs that meet search criteria (see "Searching jobs" on page 86 for details)

p4 jobs -e jobview

Jobs that were fixed by changelists that contain specific files

p4 jobs filespec

Jobs that were fixed by changelists that contain specific files, including changelists that contain files that were later integrated into the specified files

p4 jobs -i filespec

Listing jobs fixed by changelists

Any jobs that have been linked to a changelist with p4 change, p4 submit, or p4 fix are referred to as fixed (regardless of whether their status is closed). To list jobs that were fixed by changelists, issue the p4 fixes command.

The following table lists useful commands for reporting fixes.

To list
Use this command

all changelists linked to jobs

p4 fixes

all changelists linked to a specified job

p4 fixes -j jobname

all jobs linked to a specified changelist

p4 fixes -c changenum

all fixes associated with specified files

p4 fixes filespec

all fixes associated with specified files, including changelists that contain files that were later integrated with the specified files

p4 fixes -i filespec

System configuration reporting

The commands described in this section display Perforce users, client workspaces, and depots.

Displaying users

The p4 users command displays the user name, an email address, the user's "real" name, and the date that Perforce was last accessed by that user, in the following format:

bruno <bruno@bruno_ws> (bruno) accessed 2005/03/07
dai <dai@dai_ws> (Dai Sato) accessed 2005/03/04
earl <earl@earl_ws> (Earl Ashby) accessed 2005/03/07
gale <gale@gale_ws> (Gale Beal) accessed 2001/06/03
hera <hera@hera_ws> (Hera Otis) accessed 2001/10/03
ines <ines@ines_ws> (Ines Rios) accessed 2005/02/02
jack <jack@submariner> (jack) accessed 2005/03/02
mei <mei@mei_ws> (Mei Chang) accessed 2001/11/14
ona <ona@ona_ws> (Ona Birch) accessed 2001/10/23
quinn <quinn@quinn_ws> (Quinn Cass) accessed 2005/01/27
raj <raj@ran_ws> (Raj Bai) accessed 2001/07/28
vera <vera@vera_ws> (Vera Cullen) accessed 2005/01/15

Displaying workspaces

To display information about client workspaces, issue the p4 clients command, which displays the client workspace name, the date the workspace was last updated, the workspace root, and the description of the workspace, in the following format.

Client bruno_ws 2005/03/07 root c:\bruno_ws ''
Client dai-beos-locust 2002/10/03 root /boot/home/src ''
Client earl-beos-aspen 2002/04/15 root /boot/src ''
Client earl-dev-beech 2002/10/26 root /home/earl ''
Client earl-dev-guava 2002/09/08 root /usr/earl/development ''
Client earl-dev-yew 2004/11/19 root /tmp ''
Client earl-mac-alder 2002/03/19 root Macintosh HD:earl ''
Client earl-os2-buckeye 2002/03/21 root c:\src ''
Client earl-qnx-elm 2001/01/17 root /src ''
Client earl-tupelo 2001/01/05 root /usr/earl ''

Listing depots

To list depots, issue the p4 depots command. This command lists the depot's name, its creation date, its type (local, remote, or spec), its host name or IP address (if remote), the mapping to the local depot, and the system administrator's description of the depot.

For details about defining multiple depots on a single Perforce server, see the Perforce System Administrator's Guide.

Sample script

The following sample script parses the output of the p4 fstat command to report files that are opened where the head revision is not in the client workspace (a potential problem).


Perforce 2008.2 P4 User's Guide
<< Previous Chapter
Defect Tracking
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Glossary
Please send comments and questions about this manual to [email protected].
Copyright 2005-2008 Perforce Software. All rights reserved.
Last updated: 12/05/08