Chapter 11
Reporting and Data Mining
Perforce's reporting commands supply information on all data stored within the depot. Many of these reporting commands have already been mentioned in this 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, but discussion of all options for each command is beyond the scope of this manual. For a full description of all the commands, see the Perforce Command Reference, or type p4 help command at the command line.
When you use file specifications with Perforce commands, filespec arguments such as:
match any file pattern that is supplied in local syntax, depot syntax, or client syntax, with any Perforce wildcards. Brackets around [filespec] mean that the file specification is optional. Additionally, many of the reporting commands can take revision specifiers as part of the filespec. See "Specifying File Revisions" on page 53 for more about revision specifiers.
Files
Commands that report on files fall into three categories: commands that provide information about file contents, (for instance, p4 print, p4 diff), commands that provide information about the state of the mapping between your depot and the client workspace (such as p4 where and p4 have), and commands that provide information on file metadata, the data that describe a file without regards to file content (such as p4 files and p4 filelog).
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, and so on) 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)
The p4 files command requires one or more filespec arguments. Filespec arguments can, as always, be provided in Perforce or local syntax, but the output always reports on the corresponding files within the depot. If you don't provide a revision number, Perforce uses the head revision.
Unlike most other commands, p4 files also describes deleted revisions, rather than 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 any 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#revisonNum
|
|
...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. Because p4 filelog lists information about each revision of the specified file(s), file arguments to p4 filelog cannot contain revision specifications.
The output of p4 filelog has this form:
|
... #3 change 23 edit on 1997/09/26 by edk@doc <ktext> 'Fix help system'
... #2 change 9 edit on 1997/09/24 by lisag@src <text> 'Change file'
... #1 change 3 add on 1997/09/24 by edk@doc <text> 'Added filtering bug'
|
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, the file's type at that 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 file pattern argument, p4 opened prints 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
|
|
...a list of all files in a numbered pending changelist
|
p4 opened -c changelist#
|
|
...a list of all files in the default changelist
|
p4 opened -c default
|
|
...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 want to know where a particular client file is mapped to within the depot, or whether or not the head revision of a particular depot file has been copied to a client workspace.
The commands that reveal the relationship between client and depot files are p4 where, p4 have, and p4 sync -n. The first of these commands, p4 where, shows the mappings between client workspace files, depot files, and local OS syntax. p4 have tells you which revisions of files you've last synced to 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 of these commands can be used with or without filespec arguments. p4 sync -n is the only command in this set that permits the use of revision specifications on the filespec arguments.
The output of p4 where filename looks like this:
//depot/elm_proj/doc/Ref.guide //edk/doc/Ref.guide /usr/edk/doc/Ref.guide
The first part of the output is the location of the file in depot syntax; the second part is the location of the same file in client syntax, and the third is the location of the file in local OS syntax.
p4 have's output has this form:
//depot/doc/Ref.txt#3 - /usr/edk/elm/doc/Ref.txt
and p4 sync -n provides output like:
//depot/doc/Ref.txt#3 - updating /usr/edk/elm/doc/Ref.txt
The following table lists other useful commands:
To See...
|
Use This Command:
|
|---|
|
...which revisions of which files you have in the client workspace
|
p4 have
|
|
...which revision of a particular file is in your client workspace
|
p4 have filespec
|
|
...where a particular file maps to within the depot, the client workspace, and the local OS
|
p4 where filespec
|
|
...where a particular file in the depot maps to in the workspace
|
p4 where //depot/.../filespec
|
|
...which files would be synced into your client workspace from the depot when you do the next sync
|
p4 sync -n
|
File contents
Contents of a single revision
You can view the contents of any file revision within the depot 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. If a revision is specified, the file is printed at the specified revision; if no revision is specified, the head revision is 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
|
Annotated file contents
Use p4 annotate to find out which file revisions or changelists affected lines in a text file.
By default, p4 annotate displays the file, each line of which is prepended by a revision number indicating the revision that made the change. The -a option displays all lines, including lines no longer present at the head revision, and associated revision ranges. The -c option displays changelist numbers, rather than revision numbers.
Example:
Using p4 annotate to track changes to a file
A file is added (file.txt#1) to the depot, containing the following lines:
|
This is a text file.
The second line has not been changed.
The third line has not been changed.
|
The third line is deleted and the second line edited so that file.txt#2 reads:
|
This is a text file.
The second line is new.
|
Finally, a third changelist is submitted, that includes no changes to file.txt. After the
third changelist, the output of p4 annotate and p4 annotate -c look like this:
|
$ p4 annotate file.txt
//depot/files/file.txt#3 - edit change 153 (text)
1: This is a text file.
2: The second line is new.
$ p4 annotate -c file.txt
//depot/files/file.txt#3 - edit change 153 (text)
151: This is a text file.
152: The second line is new.
|
The first line of file.txt has been present since file.txt#1, as submitted in changelist
151. The second line has been present since file.txt#2, as submitted in changelist 152.
To show all lines (including deleted lines) in the file, use p4 annotate -a as follows:
|
$ p4 annotate -a file.txt
//depot/files/file.txt#3 - edit change 12345 (text)
1-3: This is a text file.
1-1: The second line has not been changed.
1-1: The third line has not been changed.
2-3: The second line is new.
|
The first line of output shows that the first line of the file has been present for revisions 1
through 3. The next two lines of output show lines of file.txt present only in revision 1.
The last line of output shows that the line added in revision 2 is still present in revision 3.
You can combine the -a and -c options to display all lines in the file and the changelist
numbers (rather than the revision numbers) at which the lines existed.
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, see 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, or even revisions of different files. The p4 diff2 command takes two file arguments: wildcards are permitted, but any wildcards in the first file argument must be matched with a corresponding wildcard in the second. Using matching wildcards in p4 diff2 makes it possible to compare entire trees of files.
There are many more flags to p4 diff than 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/path1/... //depot/path2/...
|
|
...a file within the client workspace and the revision last taken into the workspace, ignoring whitespace
|
p4 diff -dw file
|
The last example above bears further explanation; to understand how diff -dw works, it is necessary to discuss how Perforce implements and calls underlying diff routines.
Perforce uses two separate diff routines: one that is built into the p4d server, and another is used by the p4 client. Both diffs contain identical, proprietary code, but are used by separate sets of commands. The client-side diff is used by p4 diff and p4 resolve, and the server-side diff is used by p4 describe, p4 diff2, and p4 submit.
The diff algorithm accepts multiple options, including a -d flag that enables you to generate RCS-style diffs, context diffs, unified diffs, and to determine what forms of whitespace (if any) are accounted for during file comparison.
The Perforce server always uses Perforce's diff algorithm, but Perforce client programs can also use third-party diff utilities. To use a third-party diff utility, set the P4DIFF environment variable to the full path name of the utility, and pass flags to the specified diff program with the -d flag, just as you pass flags to the built-in diff routine. Flags passed to the underlying diff are subject 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.
The following examples demonstrate the use of these rules in practice.
To pass the following flag to an external client diff program:
|
Then call p4 diff this way:
|
|---|
|
-u
|
p4 diff -du
|
|
--brief
|
p4 diff -d-brief
|
|
-C 25
|
p4 diff -d'C 25'
|
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.
Viewing 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 this:
|
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, those affecting a particular file, or the last n changelists.
Currently, the output can't be restricted to changelists submitted by particular users, although you can write simple shell or Perl scripts to implement this (you'll find an example of such a script in the Perforce System Administrator's Guide).
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
|
|
...from a particular user
|
p4 changes -u user
|
|
...from a particular client workspace
|
p4 changes -c workspace
|
|
...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
|
|
...limited to those between two dates
|
p4 changes @date1,@date2
|
|
...between an arbitrary date and the present day
|
p4 changes @date1,@now
|
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.
The output of p4 describe 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
> Way number 2, what is used common-like when, you know, like
---
> The second method is commonly used when transmitting
...<etc.>
|
This output is quite lengthy, but a shortened form that eliminates the diffs can be generated with p4 describe -s changenum.
To See:
|
Use This Command:
|
|---|
|
...a list of files contained in a pending changelist
|
p4 opened -c changelist#
|
|
...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 filespec@changenum
|
For more commands that report on jobs, see "Job Reporting" on page 139.
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 all labels containing a specific revision (or range)
|
p4 labels file#revrange
|
|
...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 filespec
|
|
...what a particular p4 integrate variation would do, without actually doing the integrate
|
p4 integrate [args] -n [filespec]
|
|
...a list of all the revisions of a particular file
|
p4 filelog -i 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 list of all the revisions of a particular file, including revision of the file(s) it was branched from
|
p4 filelog -i filespec
|
Job Reporting
Two commands report on jobs. The first, p4 jobs, reports on all jobs known to the system, while the second command, p4 fixes, reports only on those jobs that have been attached to changelists. Both of these commands have numerous options.
Basic job information
To see a list of all jobs known to the system, use p4 jobs. This command 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 *closed* 'Can't read filters w'
|
Its output includes the job's name, date entered, job owner, status, and the first 31 characters of the job description.
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
|
|
...for which certain fields contain particular values (For more about jobviews, see "Viewing jobs by content with jobviews" on page 120)
|
p4 jobs -e jobview
|
|
...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 fixes looks like this:
|
job000302 fixed by change 634 on 1997/09/01 by edk@eds_elm
filter_bug fixed by change 540 on 1997/10/22 by edk@eds_elm
|
A number of options enable you to report only the set of changes that fix a particular job, the jobs fixed by a particular changelist, or jobs fixed by changelists that are linked to particular files.
A fixed job does not necessarily have a status of closed, because open jobs can be linked to pending changelists, and because pending jobs can be reopened even after the associated changelist has been submitted.
Other job reporting commands include:
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
|
|
...all jobs still open.
|
p4 jobs -e status=open
|
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 the Perforce System Administrator's Guide.
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
|
Listing Users, Workspaces, and Depots
Three commands report on the Perforce system configuration. One command reports on all Perforce users, another prints data describing all client workspaces, and a third reports on Perforce depots.
p4 users generates its data as follows:
|
edk <edk@eds_ws> (Ed K.) accessed 1997/07/13
lisag <lisa@lisas_ws> (Lisa G.) 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. See the Perforce System Administrator's Guide for more about using more than one depot on a single Perforce server.
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. This 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 simply tell you what they would ordinarily do. You can use the -n flag with the following commands
|
p4 integrate
|
p4 resolve
|
p4 labelsync
|
p4 sync
|
Please send comments and questions about this manual to
[email protected].
Copyright 1997-2004 Perforce Software. All rights reserved.
Last updated: 08/19/04