P4DB Help File

Under construction

Introduction

This page is a brief user manual for P4DB.

The reader is assumed to have working knowledge of Perforce P4 and web browsers.

What is P4DB?

P4DB is a http depot browser for Perforce p4. The depot browser is implemented as a set of CGIs that present information about the status of the p4 depot using HTML.

The purpose of P4DB is to provide a convenient way to browse the p4 depot for p4 administrators, project managers, developers, testers etc. that need information about changes in the depot.
Some typical uses for P4DB are:

P4DB can only present information in the depot and have no access to the files in the users file space.

P4DB use the standard p4 commands to retrieve information from the depot. P4DB does not add any other information but will often combine output from more than one command to get the information.

P4DB produces almost only plain html. No javascript, very little CSS (Cascades Style Sheets), one gif. P4DB use one http cookie to store user preferences.

P4DB Support and Supported Platforms

P4DB is developed using Netscape Communicator 4.7 browser and Apache http server. Both browser and server run on a Linux system.
I perform some basic testing with Explorer but that's it.

There are no supported platforms basically because there is no support. P4DB is open source software and I expect the brave p4 administrator that installs P4DB to provide support for end users. I will of course answer questions if I can and is more than willing to listen to suggestions or constructive criticism but please forward all this through your administrator.

How Do I.....? (a.k.a. FAQ)

Here is examples on how to use P4DB to answer some questions about files in the depot. The list is by no means complete but should give some idea of what P4DB can be used for.

Is there any help available?

Sure! You are looking at it, only it's not finished yet. This help page can be reached in two ways:

  1. Click on the help link at the top right corner of each page.

  2. This will usually bring you to the part in the help file that describes this current page.
  3. In some places in there are help links (currently a question mark but this may change into something more obvious).
    These links brings you directly to the paragraph in the help file that describes the adjacent feature or selection.

How do I view the latest changes in the depot?

Easy! But there are several ways:

And there are more ways. If you browse around in P4DB you will see that for virtually all items, like labels or branches, that refer to the depot you can select "View changes".

"Shortcuts", what's that?

You administrator may create one or mote of shortcut files where each file contains a set of shortcuts that are presented as links on the main page. See the "Set Preferences" page to select a shortcut file, if there are any shortcut files defined.

How to I view history for a file

There are many ways here too.

In general, in all pages that show a file name a click on the file name will show the file log.


HELP FOR PAGES

Common to all pages

Page header

To the left in the header the P4DB version information and the current change level in the depot.
At the top center of each page is a title that describes the content of the page.
To the top left of the page there is a link to the paragraph in this document that describes the current page.
Below the current level and page title there is a field that contains some more information about the page and sometimes links that links to information related to the page or change the information displayed on the page.
Below the help link there is a link to the main page, except on the main page where this place is empty.

Page Footer

To the bottom left the current p4 port and host is displayed.
To the right there is one or more mail-to-links to the administrator(s) and to the far right is a link to the page top.

Main page (or index page)

This is the start page for P4DB. The start page contains four sections:

Links to browser pages

A set of links to pages that lets you browse the depot, view pending changes, view branches or labels etc.
For detailed information click on the link and select help in the page header.

(Optional) Shortcuts

This section will only exist if the P4DB administrator have created shortcut file and you have selected one in "Set Preferences".
The section contains a set of shortcut links to various pages.

Advanced searches

This section contains a set of advanced searches with text fields for user input.

List changes for file spec

View changes for the file spec.
The file spec may contain wildcards (p4 style).
Two or more file specifications may be specified if they are separated by a "+"-sign.

Search for file

View all files in the depot matching a file specification. The file specification will typically contain wildcards (p4 style).

View change

View a change specified by change number.

Miscellaneous

This section contains three links.

  1. A link to a documentation page targeting the system administrators.
  2. A link to the "Set Preferences" page
  3. A link to "The Great Submit Race".

Set Preferences

P4DB allows the user to set some preferences. Some of the choices are defined in the configuration file by the P4DB administrator.

The preferences are:

P4 Depot
Select depot from a set of depots defined in the configuration file by the P4DB administrator. A typical installation will probably only have one single depot to choose.
 
Shortcut file to use
The P4DB administrator can define a set of shortcut files that provides handy shortcuts for the user.
 
Shortcuts on top of main page
If a shortcut file is selected the shortcuts can be displayed on top of page or not.
 
Open changes in new window
When the user selects a change number in the list of changes the change view is displayed in a new window.
 
Ignore case (like NT)
Set to "yes" if you work in a Windows environment.
 
Default tab stop
Default tab stop for your source code. If not set correctly the indentation will look funny when you view your source code.
 
Max changes to show
When changes are listed it is convenient to limit the number of changes per page or the page might take very long to load. I have found 400 to be a reasonable number in a fast LAN and probably about 20-100 or so if you work over a slow modem.
 
Hide deleted files in tree browser by default
Make "Hide deleted files" defaults in depot tree browser (as opposed to "Show deleted files")..
 
Show silly arrow next to selected link
In some menues there is a small arrow that indicates the selected option. Turn this on/off here.
 
Show tooltips
For some links a tooltip help is displayed if the mouse pointer hoovers over it. Turn this on/off here.
 
Show full descriptions in file log by default
In the file log the description can be truncated to one line or displayed in full. Set the default here.
 
View files with colors
The file viewer in P4DB can colorize HTML, perl and C code. Set this to Yes to turn this function on. Set to off (No) if you want to use a color scheme with dark background.
 
Underline links
Some people want their links underlined some don't.
 
Color scheme
Select a color scheme to use. There are a few predefined to choose from.
 
Enable experimental java depot tree browser
Once I wrote this small java applet to get a GUI to go with P4DB. Does not work in all installations but neat to have when it does.
 
Print log information
Print a log at the bottom of each page. Really only useful for debugging. Set to off.
 

Depot Tree Browser

Used to browse the file tree in the depot.
The Depot Tree Browser presents data in three sections.

  1. The top section shows the current directory in the depot.

  2. Click on a directory in the path to ascend to it.
  3. The middle section shows the currently available subdirs.

  4. Click on a subdir to descend to it.
  5. The bottom section shows the files in the current directory. Deleted files are marked with a strike through style.
    The file name links to the file log for the file. The version number links to the file viewer for latest version.

In the top of the page there is a link to view changes below current directory and a link to toggle show/hide deleted files.

P4 Users (and Groups)

Lists all users and user groups.

For each user the p4-user-name. name as specified in user description, email address and last access time is displayed. If the user has not been accessed for more than 10 weeks a message about this is printed.

Click on p4 user name to get details about user.
Click on e-mail address to send email to user.

If any groups are defined they are listed below the users. Click on group name to see details about group.

Change List

This page lists changes with different selection criteria. The selection criteria is displayed in the header.
Since the list may be very long it is limited to a specific number of changes (see Set Preferences). If there are more changes there is a "More..." link at the bottom of the page.

At the top of the page is a link that automatically lists the change descriptions for change the numbers referred to in the change description (try it and you will understand what I mean).

Search Descriptions

Search changes for text pattern in description.

The pattern fields contains a pattern that is searched for in the change descriptions.

The search is not case sensitive and the following wildcard characters are accepted:

<white space>
Matches one or more whitespace characters or newlines
*
Matches zero or more characters
?
Matches exactly one character

Depot Statistics

Shows some statistics from the depot or part of the depot.

I can't honestly say what all this is good for other than satisfying your curiosity.

The Great Submit Race

This is the great submit race. The Submit Race reads the last 499 submits and ranks the users after the number of submits.
There is also some assessment of the "speed" based on the average position of the users submits in the list.
The last user among the 499 changes gets her submit number in red. This means that this number will be decremented the next time somebody submits a change.
The user that made the most recent submit gets a green background to her submit number.

To be able to enjoy the race there is a link that replays the last 30 submits.

Please don't take the Submit Race to seriously.....