Scripting and reporting // Helix Versioning Engine User Guide

Common options used in scripting and reporting

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

Option	Description
`-b batchsize`	Specify a batch size (number of arguments) to use when processing a command from `-x argfile`. By default, 128 arguments are read at a time.
`-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 protocol:host:port`	Specifies the host and port number of the Helix server, as well as the protocol used to connect.
`-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 Helix command.
`-u user`	Specifies the Helix 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 Helix 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 -o option to write the form to standard output and the -i option to read the edited form from standard input.

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

Write a blank job specification into a text file.
```
$ p4 job -o > temp1
```

Make the necessary changes to the job.

For example:

$ sed 's/<enter description here>/Crashes on exit./' temp1 > temp2

Save the job.
```
$ p4 job -i < temp2
```

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

$ p4 job -o | sed 's/<enter description here>/Crashes on exit./' | p4 job -i

The commands that display forms are:

p4 branch
p4 change
p4 client
p4 job
p4 label
p4 submit (use p4 change -o to create changelist, or p4 submit -d "A changelist description" to supply a description to the default changelist during changelist submission.)
p4 stream
p4 user

File reporting

The sections below 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`
Summarize a `p4 sync` preview, estimate network traffic	`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:

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

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 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 @workspacename`
The files mapped by your workspace view.	*p4 files //`workspacename`/...*
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 //JamCode/dev/jam/jam.c
//JamCode/dev/jam/jam.c
... #35 change 627 edit on 2011/11/13 by earl@earl-dev-yew (text)
'Handle platform variants better'
... #34 change 598 edit on 2011/10/24 by raj@raj-althea (text)
'Reverse previous attempt at fix'
... ... branch into //JamCode/release/jam/2.2/src/jam.c#1
... #33 change 581 edit on 2011/10/03 by gale@gale-jam-oak (text)
'Version strings & release notes'

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

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:

//JamCode/dev/jam/fileos2.c- edit default change (text)

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 -asp4 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:

To display the location of a file in depot, client, and local syntax, issue the p4 where command.
To list the location and revisions of files that you last synced to your client workspace, issue the p4 have command.
To see where files will be synced in your workspace, preview the sync by issuing the p4 sync -n command.

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 option. 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 option.

Example 44. Using p4 annotate to display 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.

The output of p4 annotate and p4 annotate -c look like this:

$ p4 annotate file.txt
//Acme/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
//Acme/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 revision 1, which was submitted in changelist 151. The second line has been present since revision 2, which was 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
//Acme/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.

Monitoring changes to files

The following table lists commands that display information about the status of files, changelists, and users:

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 public changelist known to the system, as well as for any restricted changelists to which you have access. The following table lists command-line options 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` `p4 changes -s submitted` `p4 changes -s shelved`
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 label1 and label2	`p4 changes filespec@label1,@label2`
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 option. The following table lists some useful changelist reporting commands:

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 option 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`

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

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 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 Helix 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 Helix was last accessed by that user, in the following format:

bruno <bruno@bruno_ws> (bruno) accessed 2011/03/07
dai <dai@dai_ws> (Dai Sato) accessed 2011/03/04
earl <earl@earl_ws> (Earl Ashby) accessed 2011/03/07
gale <gale@gale_ws> (Gale Beal) accessed 2011/06/03
hera <hera@hera_ws> (Hera Otis) accessed 2011/10/03
ines <ines@ines_ws> (Ines Rios) accessed 2011/02/02
jack <jack@submariner> (jack) accessed 2011/03/02
mei <mei@mei_ws> (Mei Chang) accessed 2011/11/14
ona <ona@ona_ws> (Ona Birch) accessed 2011/10/23
quinn <quinn@quinn_ws> (Quinn Cass) accessed 2011/01/27
raj <raj@ran_ws> (Raj Bai) accessed 2011/07/28
vera <vera@vera_ws> (Vera Cullen) accessed 2011/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 2011/03/07 root c:\bruno_ws ''
Client earl-dev-beech 2011/10/26 root /home/earl ''
Client earl-dev-guava 2011/09/08 root /usr/earl/development ''
Client earl-dev-yew 2011/11/19 root /tmp ''
Client earl-win-buckeye 2011/03/21 root c:\src ''
Client earl-qnx-elm 2011/01/17 root /src ''
Client earl-tupelo 2011/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, archive, spec, or stream), 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 Helix installation, see the Helix Versioning Engine Administrator Guide: Fundamentals.

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):

Example 45. Sample shell script showing parsing of p4 fstat command output.

#!/bin/sh
# Usage: opened-not-head.sh files
# Displays files that are open when the head revision is not
# on the client workspace

echo=echo
exit=exit
p4=p4
sed=sed

if [ $# -ne 1 ]
then
     $echo "Usage: $0 files"
     $exit 1
fi

$p4 fstat -Ro $1 | while read line
do
     name=`$echo $line | $sed 's/^[\. ]\+\([^ ]\+\) .*$/\1/'`
     value=`$echo $line | $sed 's/^[\. ]\+[^ ]\+ \(.*\)$/\1/'`

     if [ "$name" = "depotFile" ]
     then
         depotFile=$value

     elif [ "$name" = "headRev" ]
     then
         headRev=$value

     elif [ "$name" = "haveRev" ]
     then
         haveRev=$value

         if [ $headRev != $haveRev ]
         then
             $echo $depotFile
         fi
     fi
done

Helix Versioning Engine User Guide (2016.2)

Scripting and reporting