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

  1. 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.
  2. You must have Python installed. This script has been tested using Python 2.2.
  3. (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).

3 Command Line Interface (CLI)

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

4 Graphical User Interface (GUI)

1. To launch the GUI, run p4DeltaGui.py instead of p4Delta.py. The main window will be displayed:

p4DeltaGui Main Window

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:

p4DeltaGui Main Window

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:

p4DeltaGui Main Window

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:

p4DeltaGui Main Window