Reporting
and Data Mining

Perforce's reporting commands supply information on all data stored within the depot. There are many reporting commands; in fact, there are almost as many reporting commands as there are action commands. These commands have been discussed throughout the manual; this chapter presents the same commands and provides additional information for each command. Tables in each section contain answers to questions of the form "How do I find information about...?"

Many of the reporting commands have numerous options; discussion of all options for each command is beyond the scope of this manual. For a full description of any particular command, please consult the Perforce Command Reference, or type p4 help command at the command line.

One previously mentioned note on syntax is worth repeating here: any filespec argument in Perforce commands, as in

p4 files filespec

will match any file pattern that is supplied in local syntax, depot syntax, or client syntax, with any Perforce wildcards. Brackets around filespec means that the file specification is optional.

Files

The commands that report on files fall into two categories: those that give information about file contents, (e.g. p4 print, p4 diff), and those that supply information on file metadata, the data that describe a file with no reference to content (e.g. p4 files, p4 filelog). The first set of reporting commands discussed in this section describes file metadata; the second set describes file contents.

File Metadata

Basic File Information

To view information about single revisions of one or more files, use p4 files. This command provides the locations of the files within the depot, the actions (add, edit, delete, etc.) on those files at the specified revisions, the changelists the specified file revisions were submitted in, and the files' types. The output has this appearance:

//depot/README#5 - edit change 6 (text)

p4 files requires one or more filespec arguments. Filespec arguments can, as always, be provided in Perforce or local syntax, but the output will always report the corresponding files within the depot. If no revision number is provided, the head revision will be used.

Unlike most other commands, p4 files will describe deleted revisions, instead of suppressing information about deleted files.

To View File Metadata for...	Use This Command:
...all files in the depot, whether or not visible through your client view	p4 files //depot/
..all the files currently in your client workspace	p4 files @clientname
...all the files in the depot that are mapped through your current client workspace view	p4 files //clientname/...
...a particular set of files in the current working directory	p4 files filespec
...a particular file at a particular revision number	p4 files filespec#revison#
...all files at change n, whether or not the file was actually included in change n	p4 files @n
...a particular file within a particular label	p4 files filespec@labelname

File Revision History

The revision history of a file is provided by p4 filelog. One or more file arguments must be provided, and since the point of p4 filelog is to list information about each revision of particular files, file arguments to this command may not contain a revision specification.

The output of p4 filelog has this form:

... #3 change 23 edit on 1997/09/26 by edk@doc 'Updated hel'
... #2 change 9 edit on 1997/09/24 by lisag@src 'Made chang'
... #1 change 3 add on 1997/09/24 by edk@doc 'Added the f'

For each file that matches the filespec argument, the complete list of file revisions is presented, along with the number of the changelist that the revision was submitted in, the date of submission, the user who submitted the revision, and the first few characters of the changelist description. With the -l flag, the entire description of each changelist is printed:

... #3 change 23 edit on 1997/09/26 by edk@doc
Updated help files to reflect changes
in filtering system & other subsystems
...<etc.>

Opened Files

To see which files are currently opened within a client workspace, use p4 opened. For each opened file within the client workspace that matches a filepattern argument, p4 opened will print a line like the following:

//depot/elm_proj/README - edit default change (text)

Each opened file is described by its depot name and location, the operation that the file is opened for (add, edit, delete, branch, or integrate), which changelist the file is included in, and the file's type.

To See...	Use This Command:
...a listing of all opened files in the current workspace	p4 opened
...a list of all opened files in all client workspaces	p4 opened -a
...whether or not a specific file is opened by you	p4 opened filespec
...whether or not a specific file is opened by anyone	p4 opened -a filespec

Relationships Between Client and Depot Files

It is often useful to know how the client and depot are related at a particular moment in time. Perhaps you simply want to know where a particular client file is mapped to within the depot, or you may want to know whether or not the head revision of a particular depot file has been copied to the client. The commands that express the relationship between client and depot files are p4 where, p4 have, and p4 sync -n. The first of these commands, p4 where, is used to determine where client files would be mapped through the client view into the depot, and vice-versa. p4 have tells you which depot files and revisions are available within your client workspace, and p4 sync -n describes which files would be read into your client workspace the next time you perform a p4 sync.

All these commands can be used with or without filespec arguments. p4 sync -n is the only command in this set that allows revision specifications on the filespec arguments.

The output of p4 where looks like this:

//depot/elm_proj/doc/Ref.guide: //edk/doc/Ref.guide

p4 have's output has this form:

//depot/doc/Ref.guide#3 - /u1/rlo/edk/elm/doc/Ref.guide

and p4 sync -n provides output like:

//depot/doc/Ref.guide#3 - updating /usr/edk/elm/doc/Ref.guide

File Contents

Contents of a Single Revision

The contents of any file revision within the depot can be viewed with p4 print. This command simply prints the contents of the file to standard output, or to the specified output file, along with a one-line banner that describes the file. The banner can be removed by passing the -q flag to p4 print. When printed, the banner has this format:

//depot/elm_proj/README#23 - edit change 50 (text)

p4 print takes a mandatory file argument, which can include a revision specification; The file will be printed at the specified revision; if no revision is specified, the head revision will be printed.

To See the Contents of Files...	Use This Command:
...at the current head revision	p4 print filespec
...without the one-line file header.	p4 print -q filespec
...at a particular change number	p4 print filespec@changenum

File Content Comparisons

A client workspace file can be compared to any revision of the same file within in the depot with p4 diff. This command takes a filespec argument; if no revision specification is supplied, the workspace file is compared against the revision last read into the workspace.

The p4 diff command has many options available; only a few are described in the table below. For more details, please consult the Perforce Command Reference.

Whereas p4 diff compares a client workspace file against depot file revisions, p4 diff2 can be used to compare any two revisions of a file. It can even be used to compare revisions of different files. p4 diff2 takes two file arguments; wildcards are allowed, but any wildcards in the first file argument must be matched with a corresponding wildcard in the second. This makes it possible to compare entire trees of files.

There are many more flags to p4 diff then are described below. For a full listing, please type p4 help diff at the command line, or consult the Perforce Command Reference.

To See the Differences between...	Use This Command:
...an open file within the client workspace and the revision last taken into the workspace	p4 diff file
...any file within the client workspace and the revision last taken into the workspace	p4 diff -f file
...a file within the client workspace and the same file's current head revision	p4 diff file#head
...a file within the client workspace and a specific revision of the same file within the depot	p4 diff file#revnumber
...the n-th and head revisions of a particular file	p4 diff2 filespec filespec#n
...all files at changelist n and the same files at changelist m	p4 diff2 filespec@n filespec@m
...all files within two branched codelines	p4 diff2 //depot/codeline1/... //depot/codeline2/...
...a file within the client workspace and the revision last taken into the workspace, passing the context diff flag to the underlying diff.	p4 diff -dc file

The last example above bears further explanation; to understand how this works, it is necessary to discuss how Perforce implements and calls underlying diff routines.

Perforce uses two separate diffs: one is built into the p4d server, and the other is used by the p4 client. Both diffs contain identical, proprietary code, but are used by separate sets of commands. The client diff is used by p4 diff and p4 resolve, and the server diff is used by p4 describe, p4 diff2, and p4 submit.

Perforce's built-in diff routine allows three -d<flag> flags: -du, -dc, and -dn; both p4 diff and p4 diff2 allow any of these flags to be specified. These flags behave identically to the corresponding flags in the standard UNIX diff.

Although the server must always use Perforce's internal diff routine, the client diff can be set to any external diff program by pointing the P4DIFF environment variable to the full path name of the desired executable. Any flags used by the external diff can be passed to it with p4 diff's -d flag. Flags are passed to the underlying diff according to the following rules:

• If the character immediately following the -d is not a single quote, then all the characters between the -d and whitespace are prepended with a dash and sent to the underlying diff;
• If the character immediately following the -d is a single quote, then all the characters between the opening quote and the closing quote are prepended with a dash and sent to the underlying diff.

Changelists

Two separate commands are used to describe changelists. The first, p4 changes, lists changelists that meet particular criteria, without describing the files or jobs that make up the changelist. The second command, p4 describe, lists the files and jobs affected by a single changelist. These commands are described below.

Changelists that Meet Particular Criteria

To view a list of changelists that meet certain criteria, such as changelists with a certain status, or changelists that affect a particular file, use p4 changes. The output looks like the following:

Change 36 on 1997/09/29 by edk@eds_elm 'Changed filtering me'
Change 35 on 1997/09/29 by edk@eds_elm 'Misc bug fixes: fixe'
Change 34 on 1997/09/29 by lisag@lisa 'Added new header inf'

By default, p4 changes displays an aggregate report containing one line for every changelist known to the system, but command line flags and arguments can be used to limit the changelists displayed to those of a particular status, or those affecting a particular file, or the last n changelists. Currently, the output can't be restricted to changelists submitted by particular users, although simple shell or Perl scripts can be written to implement this.

To See a List of Changelists...	Use This Command:
...with the first 31 characters of the changelist descriptions	p4 changes
...with the complete description of each changelist	p4 changes -l
...including only the last n changelists	p4 changes -m n
...with a particular status (pending or submitted)	p4 changes -s status
...limited to those that affect particular files	p4 changes filespec
...limited to those that affect particular files, but including changelists that affect files which were later integrated with the named files	p4 changes -i filespec
...limited to changelists that affect particular files, including only those changelists between revisions m and n of these files	p4 changes filespec#m,#n
...limited to those that affect particular files at each files revisions between labels lab1 and lab2	p4 changes filespec@lab1,@lab2

Files and Jobs
Affected by Changelists

To view a list of files and jobs affected by a particular changelist, along with the diffs of the new file revisions and the previous revisions, use p4 describe. Its output looks like this:

Change 43 by lisag@warhols on 1997/08/29 13:41:07 Made grammatical changes to basic Elm documentation Jobs fixed ... job000001 fixed on 1997/09/29 by edk@edk Fix grammar in main Elm help file Affected files ... ... //depot/doc/elm.1#2 edit Differences ... ==== //depot/doc/elm.1#2 (text) ==== 53c53 < The second way, used most commonly when transmitting --- > The second way, which is commonly used when transmitting ...<etc.>

This output is quite lengthy; a shortened form that eliminates the file diffs can be generated with p4 describe -s changenum.

To See:	Use This Command:
...a list of all files submitted and jobs fixed by a particular changelist, displaying the diffs between the file revisions submitted in that changelist and the previous revisions	p4 describe changenum
...a list of all files submitted and jobs fixed by a particular changelist, without the file diffs	p4 describe -s changenum
...a list of all files and jobs affected by a particular changelist, while passing the context diff flag to the underlying diff program	p4 describe -dc changenum
...the state of particular files at a particular changelist, whether or not these files were affected by the changelist	p4 files @changenum filespec

Labels

Reporting on labels is accomplished with a very small set of commands. The only command that reports only on labels, p4 labels, prints its output in the following format:

Label release1.3 1997/5/18 'Created by edk'
Label lisas_temp 1997/10/03 'Created by lisag'
...<etc.>

The other label reporting commands are variations of commands we've seen earlier.

To See:	Use This Command:
...a list of all labels, the dates they were created, and the name of the user who created them	p4 labels
...a list of files that have been included in a particular label with p4 labelsync	p4 files @labelname
...what p4 sync would do when retrieving files from a particular label into your client workspace	p4 sync -n @labelname

Branch and Integration Reporting

The plural form command of branch, p4 branches, lists the different branches in the system, along with their owners, dates created, and descriptions. Separate commands are used to list files within a branched codeline, to describe which files have been integrated, and to perform other branch-related reporting. The table below describes the most commonly used commands for branch- and integration- related reporting.

To See:	Use This Command:
...a list of all branches known to the system	p4 branches
...a list of all files in a particular branched codeline	p4 files filespec1
...what a particular p4 integrate variation would do, without actually doing the integrate.	p4 integrate [args] -n [filespec]
...what a particular p4 resolve variation would do, without actually doing the resolve.	p4 resolve [args] -n [filespec]
...a list of files that have been resolved but have not yet been submitted	p4 resolved [filespec]
...a list of integrated, submitted files that match the filespec arguments	p4 integrated filespec
...a description of the revision history of the named files, including the following for each file revision: change number; operation (add, edit, delete, branch, or integrate) client name; user name; and description.	p4 filelog [filespec]

1 In this case, the filespec should be presented in depot syntax, and should represent the branched codeline. For example, if a codeline had been branched to //depot/r22/..., then a list of all files in the branched codeline would be obtained with p4 files //depot/r22/...

Job Reporting

Job reporting is accomplished with two commands. The first, p4 jobs, reports on all jobs known to the system; the second command, p4 fixes, reports only on those jobs that have been attached to changelists. Both these commands have numerous options.

Basic Job Information

To see a list of all jobs known to the system, use p4 jobs. Options to this command can be used to specify criteria for describing only particular types of jobs; for example, the -s flag will limit the report to jobs of a particular status. p4 jobs produces output similar to the following:

job000302 on 1997/08/13 by saram *open* 'FROM: headers no'
filter_bug on 1997/08/23 by edk 'Can't read filters w'

Its output includes the jobs name, date entered, job owner, and the first 32 characters of the job description. The job status is included if the job is open or suspended; closed jobs are indicated by the absence of job status from the report.

All jobs known to the system are displayed unless command-line options are supplied. These options are described in the table below.

To See a List of Jobs:	Use This Command:
...including all jobs known to the server	p4 jobs
...including the full texts of the job descriptions	p4 jobs -l
...of a particular status (open, closed, or suspended)	p4 jobs -s status
...that have been fixed by changelists that contain specific files	p4 jobs filespec
...that have been fixed by changelists that contain specific files, including changelists that contain files that were later integrated into the specified files.	p4 jobs -i filespec

Jobs, Fixes, and Changelists

Any jobs that have been linked to a changelist with p4 change, p4 submit, or p4 fix is said to be fixed, and can be reported with p4 fixes. The output of p4 fix looks like this:

job000302 fixed by change 634 on 1997/09/01 by edk@eds_mach
filter_bug fixed by change 540 on 1997/10/22 by edk@eds_mach

A number of options allow the reporting of only those changes that fix a particular job, or jobs fixed by a particular changelist, or jobs fixed by changelists that are linked to particular files.

A fixed job is not the same as a closed job, since open jobs can be linked to pending changelists, and pending jobs can be reopened even after the associated changelist has been submitted. To list jobs with a particular status, use p4 jobs.

To See a Listing of...	Use This Command:
...all fixes for all jobs	p4 fixes
...all changelists linked to a particular job	p4 fixes -j jobname
...all jobs linked to a particular changelist	p4 fixes -c changenum
...all jobs fixed by changelists that contain particular files	p4 fixes filespec
...all jobs fixed by changelists that contain particular files, including changelists that contain files that were later integrated with the specified files	p4 fixes -i filespec

Reporting for Daemons

The Perforce change review mechanism uses the following reporting commands. Any of these commands might also be used with user-created daemons. For further information on daemons, please see chapter 11, and consult the source code of the Perforce Change Review daemon.

To list...	Use This Command:
...the names of all counter variables currently used by your Perforce system	p4 counters
...the numbers of all changelists that have not yet been reported by a particular counter variable	p4 review -t countername
...all users who have subscribed to review particular files	p4 reviews filespec
...all users who have subscribed to read any files in a particular changelist	p4 reviews -c changenum
...a particular user's email address	p4 users username

System Configuration

Three commands report on the Perforce system configuration. One command reports on all Perforce users; another prints data describing all Perforce client workspaces, and a third reports on Perforce depots.

p4 users generates its data as follows:

edk <edk@eds_ws> (Ed Kuepper) accessed 1997/07/13
lisag <lisa@lisas_ws> (Lisa Germano) accessed 1997/07/14

Each line includes a username, an email address, the user's "real" name, and the date that Perforce was last accessed by that user.

To report on client workspaces, use p4 clients:

Client eds_elm 1997/09/12 root /usr/edk 'Ed's Elm workspace'
Client lisa_doc 1997/09/13 root /usr/lisag 'Created by lisag.'

Each line includes the client name, the date the client was last updated, the client root, and the description of the client.

Depots can be reported with p4 depots. All depots known to the system are reported on; the described fields include the depot's name, its creation date, its type (local or remote), its IP address (if remote), the mapping to the local depot, and the system administrator's description of the depot.

To view:	Use This Command:
...user information for all Perforce users	p4 users
...user information for only certain users	p4 users username
...brief descriptions of all client workspaces	p4 clients
...a list of all defined depots	p4 depots

Special Reporting Flags

Two special flags, -o and -n, can be used with certain action commands to change their behavior from action to reporting.

The -o flag is available with most of the Perforce commands that normally bring up forms for editing. This flag tells these commands to write the form information to standard output, instead of bringing the definition into the user's editor.

The -o flag is supported by the following commands:

p4 branch	p4 client	p4 label
p4 change	p4 job	p4 user

The -n flag prevents commands from doing their job. Instead, the commands will simply tell you what they would ordinarily do.

The -n flag can be used with the following commands:

p4 integrate	p4 resolve
p4 labelsync	p4 sync

Reporting with Scripting

Although Perforce's reporting commands are sufficient for most needs, there may be times when you want to view data in a format that Perforce doesn't directly support. In these situations, the reporting commands can be used in combination with scripts to print only the data that you want to see. Three examples are provided here.

Comparing the Change Content of Two File Sets

To compare the "change content" of two sets of files, it is necessary to diff them externally. To do this, run p4 changes twice, once on each set of files, and then use any external diff routine to compare them.

In the following example, main represents the main codeline, and r98.4 is a codeline that was originally branched from main:

p4 changes //depot/main/... > changes-in-main
p4 changes //depot/r98.4/... > changes-in-r98.4
diff changes-in-main changes-in-r98.4

This could be used to uncover which changes have been made to r98.4 that haven't been integrated back into main.

Changelists Submitted by Particular Users

The p4 changes command does not have a flag that allows only those changes submitted by particular users to be viewed, but this can be accomplished by grepping the output of p4 changes. For example, in the Korn shell, create an executable file with these contents:

p4 changes | grep '.* by '$1'@

When this script is called with a username as an argument, only those changes created by that user will be printed.

Listing Subdirectories of the Depot

Although all files in the depot can be listed with p4 files, there is no option for reporting only the names of subdirectories within the depot. However, this can be accomplished with the following Perl script, which takes file arguments in either Perforce or local syntax:

open(P4,"p4 files " . join(' ',@ARGV) . " |");
while(<P4>) {
s@^(.*)/[^/]*#.*$@$1@;
if(!exists $d{$_}) {
print;
$d{$_}=42;
}
}

These scripting examples are, of course, non-exhaustive. Use scripts whenever you want to generate reports that can't be created through existing Perforce commands.