p4Delta.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 
<!-- $Id: //guest/mitch_stuart/perforce/utils/delta/doc/p4Delta.html#1 $ -->
 
<html>
<head>
<link rel="stylesheet" type="text/css" href="styles.css" />   
<title>p4Delta</title>
</head>
<body>
 
<h2>p4Delta</h2>
 
<h3>1 Introduction</h3>
p4Delta.py finds the <i>delta</i> between two filesets.  The <i>delta</i> is the list of files that have been added, removed, or
updated.  A <i>fileset</i> 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.
 
<p />
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.
 
<p />
Perforce provides some facilities for getting this information.  For example, there is a <a href="http://www.perforce.com/perforce/technotes/note043.html">technote</a> that describes how to display the difference between two labels.  However, neither the technique nor the output is particularly "user friendly". 
 
<p />
p4Delta has two interfaces:
 
<ul>
<li><a href="#CommandLineInterface">Command Line Interface (CLI)</a></li>
 
<p />
<li><a href="#GraphicalUserInterface">Graphical User Interface (GUI)</a></li>
</ul>
 
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. 
 
<h3>2 Environment Requirements</h3>
<ol>
<li>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.</li>
 
<p />
<li>You must have Python installed.  This script has been tested using Python 2.2.</li>
 
<p />
<li>(Optional) If you want to use the GUI, you must have <a href="http://wxpython.org/">wxPython</a> 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).</li>
</ol>
 
 
<h3><a name="CommandLineInterface">3 Command Line Interface (CLI)</a></h3>
p4Delta.py supports two command line formats:
 
<p />
(a) General syntax that finds the delta between any two filesets:
 
<pre><code>  p4Delta.py <i>dirspec1</i> <i>filespec1</i> <i>dirspec2</i> <i>filespec2</i></code></pre>
 
(b) Shortcut syntax that finds the delta between any two points in time
   in the same branch or directory:
 
<pre><code>  p4Delta.py <i>dirspec</i> <i>filespec1</i> <i>filespec2</i></code></pre>
 
Guidelines regarding when to use General versus Shortcut syntax are given following the
examples section below.
 
<h4>3.1 Sample Invocation</h4>
This example uses the Shortcut syntax to display the delta between two labels in the same branch.
 
<pre><code>  p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-1 ...@suzuki-label-5</code></pre>
 
<h4>3.2 Sample Output</h4>
 
<pre><code>  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
    . . .
</code></pre>
 
<h4>3.3 File and Directory Specs</h4>
File and directory specifications can be in any <a href="http://www.perforce.com/perforce/doc.022/manuals/cmdref/o.fspecs.html">syntax supported by Perforce</a>:
depot syntax, client syntax, or local filesystem syntax.
 
<p />
A <i>dirspec</i> 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:
 
<pre><code>   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]</code></pre>
 
<p />
A <i>filespec</i> 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
<a href="http://www.perforce.com/perforce/doc.022/manuals/cmdref/o.fspecs.html">Perforce File Specification</a> 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:
 
<pre><code>   "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"]</code></pre>
 
<h4>3.4 Examples</h4>
Delta between two labels:
 
<pre><code>  p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...@suzuki-label-4</code></pre>
 
<p />
Delta between two labels (specific file):
 
<pre><code>  p4Delta.py //depot/dev/console/suzuki myfile.c@suzuki-label-3 myfile.c@suzuki-label-4</code></pre>
 
<p />
Delta between a label and the current depot contents:
 
<pre><code>    p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...</code></pre>
 
<p />
Delta between a label and the current client contents:
 
<pre><code>    p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...#have</code></pre>
 
<p />
Delta between a date and the current depot contents:
 
<pre><code>    p4Delta.py //depot/dev/console/suzuki ...@2003/07/01 ...</code></pre>
 
<p />
Delta between the current client contents and the current depot contents
(similar to p4 sync -n: shows what is out of date):
 
<pre><code>    p4Delta.py //depot/dev/console/suzuki ...#have ...</code></pre>
 
<p />
Delta between two branches:
 
<pre><code>    p4Delta.py //depot/dev/console/ducati ... //depot/dev/console/suzuki ...</code></pre>
 
<p />
Delta between two branches, with specific labels:
 
<pre><code>    p4Delta.py //depot/dev/console/ducati ...@ducati-build-3 //depot/dev/console/suzuki ...@suzuki-build-2</code></pre>
 
 
<h4>3.5 Comparison of Syntax Forms</h4>
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.
 
<p />
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 <b>must</b> use the General syntax.
 
<p />
For example, this command in Shortcut syntax:
 
<pre><code>  p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 ...@suzuki-label-4</code></pre>
 
<p />
can be expressed as follows in General syntax:
 
<pre><code>  p4Delta.py //depot/dev/console/suzuki ...@suzuki-label-3 //depot/dev/console/suzuki ...@suzuki-label-4</code></pre>
 
<p />
The results of the two commands are the same, the General syntax just requires
more typing.
 
<h4>3.6 Order of Arguments</h4>
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:
 
<pre><code>  p4Delta.py //depot/myprog ...@label1 ...@label2</code></pre>
 
<p />
will show the delta between label1 and label2.  If you instead run:
 
<pre><code>  p4Delta.py //depot/myprog ...@label2 ...@label1</code></pre>
 
<p />
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:
 
<pre><code>  p4Delta.py //depot/myprog/rel1 ... //depot/myprog/rel2 ...</code></pre>
 
<p />
   or
 
<pre><code>  p4Delta.py //depot/myprog/rel2 ... //depot/myprog/rel1 ...</code></pre>
 
<p />
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.
 
<h4>3.7 Relation of Arguments</h4>
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
 
<pre><code>  p4Delta.py //depot/dir1 ... //depot/dir2 ...</code></pre>
 
<p />
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".
 
<h3><a name="GraphicalUserInterface">4 Graphical User Interface (GUI)</a></h3>
1.  To launch the GUI, run p4DeltaGui.py instead of p4Delta.py.  The main window will be displayed:
 
<p />
<img src="images/p4DeltaGui-main-window.gif" alt="p4DeltaGui Main Window" style="margin-left: 2em;" />
 
<p />
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:
 
<p />
<img src="images/p4DeltaGui-select-dir.gif" alt="p4DeltaGui Main Window" style="margin-left: 2em;" />
 
<p />
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:
 
<p />
<img src="images/p4DeltaGui-select-qualifier.gif" alt="p4DeltaGui Main Window" style="margin-left: 2em;" />
 
<p />
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.
 
<p />
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.
 
<p />
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:
 
<p />
<img src="images/p4DeltaGui-results.gif" alt="p4DeltaGui Main Window" style="margin-left: 2em;" />
 
</body>
</html>
#	Change	User	Description	Committed
#1	3652	Mitch Stuart	Initial checkin	22 years ago