p4Delta
1 Introduction
p4Delta.py finds the delta between two filesets. The delta is the list of files that have been added, removed, or
updated. A fileset is a group of one or more files that can be described with
a Perforce directory/file specification. Perforce wildcards and modifiers
(labels, dates, etc.) can be used to specify the fileset.
p4Delta is typically used to show the delta between two branches, labels, or timestamps. For example, if you want to know what has changed between myproject-label3 and myproject-label4, p4Delta will show you.
Perforce provides some facilities for getting this information. For example, there is a technote that describes how to display the difference between two labels. However, neither the technique nor the output is particularly "user friendly".
p4Delta has two interfaces:
Even if you intend to use the GUI, you should read the documentation for the CLI, because it explains the terminology, concepts, and behavior of p4Delta.
2 Environment Requirements
- This script invokes the Perforce p4 command-line interface to get the
needed information from Perforce. The p4 command must be available on your
PATH, and you must have configured your environment so that the p4 command
is able to access the Perforce server.
- You must have Python installed. This script has been tested using Python 2.2.
- (Optional) If you want to use the GUI, you must have wxPython installed. This script has been tested using wxPython 2.4.1.2. The GUI should work on any platform where wxPython is supported, however it has only been tested on Windows XP and Linux/GTK (Red Hat 7.3).
p4Delta.py supports two command line formats:
(a) General syntax that finds the delta between any two filesets:
p4Delta.py dirspec1 filespec1 dirspec2 filespec2
(b) Shortcut syntax that finds the delta between any two points in time
in the same branch or directory:
p4Delta.py dirspec filespec1 filespec2
Guidelines regarding when to use General versus Shortcut syntax are given following the
examples section below.
3.1 Sample Invocation
This example uses the Shortcut syntax to display the delta between two labels in the same branch.
p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-1 ...@suzuki-label-5
3.2 Sample Output
Removed Files:
manager/web/processMBeanChanges.jsp
Added Files:
JConsole/CondenserXMLUtil.java
JConsole/DottedVersionNumber.java
JConsole/StringMapper.java
. . .
Updated Files:
JConsole/CAppContextBase.java
JConsole/CReportDataMgrPerf.java
JConsole/DbUtil.java
. . .
3.3 File and Directory Specs
File and directory specifications can be in any syntax supported by Perforce:
depot syntax, client syntax, or local filesystem syntax.
A dirspec is the name of a directory. It may be absolute (with a full path
from the root) or relative to the current directory. It must not end with
a file separator character (/ or \) and it must not include any filename
component. Examples of valid dirspecs are:
dir1 [local syntax, relative]
C:\dev\dir1 [local syntax, absolute]
/home/jdoe/dev/dir1 [local syntax, absolute]
//depot/dev/dir1 [Perforce depot syntax]
//jdoe/dev/dir1 [Perforce client syntax]
A filespec is the name of a file. It may include Perforce wildcards.
It may include a Perforce modifier such as a branch name, date, etc. (See the
Perforce File Specification documentation for details on modifiers.)
The filespec must not include any directory component. When the filespec includes
wildcards or modifiers, it often needs to be quoted to prevent the shell
from expanding the argument. Examples of valid filespecs are:
"myfile.c" [specific file]
"myfile.c@label1" [specific file with label]
"*" [all files in dir (but not subdirs)]
"..." [all files in dir and subdirs]
"*@label1" [all files in dir with label]
"...@label1" [all files with label]
"...@2003/07/01" [all files as of date]
"...@2003/07/01 13:15:00" [all files as of date/time]
"...#have" [all files current version in client workspace]
"...#head" [all files current version in depot - same as "..."]
"..." [all files current version in depot - same as "...#head"]
3.4 Examples
Delta between two labels:
p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...@suzuki-label-4
Delta between two labels (specific file):
p4Delta.py //depot/dev/console/suzuki myfile.c@suzuki-label-3 myfile.c@suzuki-label-4
Delta between a label and the current depot contents:
p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...
Delta between a label and the current client contents:
p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...#have
Delta between a date and the current depot contents:
p4Delta.py //depot/dev/console/suzuki ...@2003/07/01 ...
Delta between the current client contents and the current depot contents
(similar to p4 sync -n: shows what is out of date):
p4Delta.py //depot/dev/console/suzuki ...#have ...
Delta between two branches:
p4Delta.py //depot/dev/console/ducati ... //depot/dev/console/suzuki ...
Delta between two branches, with specific labels:
p4Delta.py //depot/dev/console/ducati ...@ducati-build-3 //depot/dev/console/suzuki ...@suzuki-build-2
3.5 Comparison of Syntax Forms
The Shortcut syntax is simply provided for convenience, because in most cases the
filespec between the two delta points of interest is the same, it is only the
modifier (the branch name, date, etc.) that is different.
Any command written in the Shortcut syntax can be rewritten in the General syntax, but the reverse is not true: when you are delta'ing different directories or branches, you must use the General syntax.
For example, this command in Shortcut syntax:
p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...@suzuki-label-4
can be expressed as follows in General syntax:
p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 //depot/dev/console/suzuki ...@suzuki-label-4
The results of the two commands are the same, the General syntax just requires
more typing.
3.6 Order of Arguments
Just as with any "diff" type utility, the order that you specify the
arguments is important: generally, you want the "earlier" argument on the
left and the "later" argument on the right. For example:
p4Delta.py //depot/myprog ...@label1 ...@label2
will show the delta between label1 and label2. If you instead run:
p4Delta.py //depot/myprog ...@label2 ...@label1
then the sense of the delta will be reversed. In other words, files that
were removed between label1 and label2 will be shown as having been
added between label2 and label1.
Labels usually have a known sequence that makes it easy to determine the
correct order for the arguments. But for branches, when you have parallel
development, there is no automatic way to know which of the following
will produce the most useful output:
p4Delta.py //depot/myprog/rel1 ... //depot/myprog/rel2 ...
or
p4Delta.py //depot/myprog/rel2 ... //depot/myprog/rel1 ...
Both commands will show you the delta between the branches, but depending
on which branch you are more familiar with, or which branch has been more
active, you may find one output is easier to work with than the other.
You can just try both commands and see which one you prefer.
3.7 Relation of Arguments
Just as with any "diff" type utility, running a delta only makes sense if
there is some relationship between the filespecs. For example, if you run
p4Delta.py //depot/dir1 ... //depot/dir2 ...
on two random directories, dir1 and dir2, that are not related by any
branching or other common ancestry, the output will not be useful. It will
simply tell you that every file in dir1 has been "deleted" and every file
in dir2 has been "added".
1. To launch the GUI, run p4DeltaGui.py instead of p4Delta.py. The main window will be displayed:
2. Specify the first directory. You can either type in a directory name, or use the "Select..." button to browse for a directory in the depot:
3. Specify the first filespec. You can either type in a filespec, or use the "Select..." button to assist in creating a filespec using a label or other modifier:
4. Specify the second directory. Select "Same as Dir 1" to use the same directory that you specified above for Dir 1. Select "Other Dir" to specify a different directory. If you select "Other Dir", you can either type in a directory name, or use the "Select..." button to browse for a directory in the depot.
5. Specify the second filespec. You can either type in a filespec, or use the "Select..." button to assist in creating a filespec using a label or other modifier.
6. Click the Delta button to display the delta between the two dirspec/filespec combinations that you specified. The delta is displayed in the Results field:
