Installing P4QTree is as simple as putting the software in your PATH. On Windows, for example, put p4qtree.exe and qt-mt306.dll in your Perforce installation directory (C:\Program Files\Perforce by default). You can then invoke P4QTree from the command line, or from other applications. The syntax is p4qtree [options] filename.
Most of P4QTree's options are set via the Preferences dialog. Diff tools, however, should be set as environment or registry variables. The text diff tool is specified by P4DIFF, the same variable that the command line uses. If you're using Windows and want to use P4Win's P4Diff as your diff tool, just run p4 set P4DIFF=p4diff.
P4QTree also supports the definition of a single diff program for binaries, such as images. The binary diff program is set via the P4DIFFBIN variable, which is not a standard Perforce client variable. For example, to set SQUID as your binary diff program on Windows, run p4 set P4DIFFBIN=squid.
Standard Perforce settings (port, user, client, password) are inherited automatically from the environment, registry, or P4CONFIG files, just as with the command line. P4QTree also supports the standard global options passed in on the command line, eg: p4qtree -p public.perforce.com:1666 //public/jam/index.html.
-F filename.txt
allows you to feed P4QTree p4 filelog
output in lieu of (or in addition to) data directly from a Perforce server. Put all of the p4 filelog data into the named text file, and P4QTree will read data from that file (if available) to build its graph. (Be sure not to use the -i or -l options to p4 filelog, as the parser isn't equipped to handle anything but standard filelog format!)
-o filename.png
tells P4QTree to generate its graph, dump the result to a PNG file, and exit. If the graph is too large for the uncompressed image to fit in memory, this will fail and you'll get nothing.
-n
causes the files to be sorted alphabetically from top to bottom. Support for this is partial in that it only works for the initially generated graph; subsequent refreshes will use the default sort order.
The Preferences dialog is under the File menu. It is used to set all the options that aren't handled by command-line arguments or environment variables.
The Colors tab lets you select a color scheme. The names have no special significance. Note that the Old-School color scheme differentiates revision actions by circle color, whereas the Post-Modern scheme colors all non-delete revisions uniformly.
The Queries tab handles options regarding queries made to the Perforce server. Checking Disable jobs will entirely disable all job-related features, thus eliminating a long string of p4 fixes queries. Checking Show all integs will tell P4QTree to follow integrations that do not have any direct or indirect bearing on the highlighted file; this will increase the graph size and the number of p4 filelog queries.
The Cropping tab allows you to crop results by date; this is implemented via a combination of modifying filelog queries (for the end of the range) and post-processing (for the beginning of the range). If the dates are poorly chosen, you may end up with an empty graph.
Everything in the main field of view represents a Perforce entity and can be interacted with. Clicking on the background will create a black vertical line; this is meant as a visual aid to line revisions up with changes. Another click will dismiss it. All interactive items will produce tooltips when hovered over. Any errors encountered by P4QTree during an operation, including on refresh or startup, will be displayed in a dialog.
Double-clicking an item will always yield a dialog with additional information about that item. Changes and jobs will query the Perforce server to get this information. Files and revisions will produce information that has already been gathered by P4QTree while the graph was generated. If P4Win is installed, the file and revision dialogs will include a button that will launch P4Win's Revision History dialog to provide additional features.
Dragging an item will produce a standard text drag that refers to that item in standard Perforce syntax, eg //depot/dir/foo#2 or job000123. These bits of text can be dropped into any application that supports text drags. Dropping a file or revision onto another file or revision will generate a diff of the two files, using the program specified via P4DIFF or P4DIFFBIN as appropriate. In addition, dropping any item into its corresponding pane in P4Win will tell P4Win to highlight that item if it exists there - this is particularly handy for quickly finding branched versions of files.
The View menu contains three hotkeyed commands that modify or augment the main view.
Toggle jobs simply hides and shows the job bar, which can be useful when trying to view a graph which includes a lot of jobs. Note that this is different from the Disable jobs preference in that it does not modify server queries in any way.
Branching-only View spawns a new window which only shows revisions that are involved in integration. This makes it easier to find key integration points, but also makes it impossible to identify changes and fixes that happened in between integrations.
Refresh is obvious.
The top bar in the window contains changelists organized along the x-axis in numerical (and hence chronological) order. Each changelist is found directly above the revision(s) that it created. The jobs bar, directly below the changes bar, displays the fixes associated with those changelists, and by extension with those file revisions.
The rest of the view displays the file that P4QTree was invoked on (this file is highlighted), as well as all of the files related to it by integration (and some unrelated files if Show All Integs is checked). Each file is a horizontal stripe, with the revisions in that file represented as numbered circles. Arrows in between revisions indicate relationships between them, which can be either operations on that file (horizontal arrows), or integrations between files (curved arrows). The specific type of integration is indicated by color (hit F1 to see what each color signifies). The thickness/solidity of arrows indicates how much the source revision contributed to the target revisions. A thick line indicates that the two revisions are identical, a medium line indicates that the source contributed itself partially to the target, and a thin dotted line indicates that the relationship being represented does not include any actual contribution of file content.
P4QTree's source is available in the Perforce Public Depot. It is built with the Qt GUI toolkit.
P4QTree is not supported by Perforce Software, but you can contact the author at samwise at per force dot com with questions, comments, et cetera.