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:

• View diff between file revisions
• Find out when a line in a file was changed
• View labels
• List changes between labels or for a specific set of files
• Stay abreast with the development

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.

This will usually bring you to the part in the help file that describes this current page.
2. 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:

• By far the easiest is to click on "Submitted Changes" in the main page. This will show the submitted changes in reverse chronological order, that is the latest on top.
• If you are not interested in the whole depot you could select "Browse Depot Tree" on the main page. Using the browser you can move down the depot tree and select "View changes".
• If you are interested in a special file or set of files you could enter a file spec (in p4 depot notation) in the "List Changes For File spec" field in the main page. If you, for example, enter //.../main/.../*.doc you will see the changes for all files with extension ".doc" below a directory named "main"
  You can change file spec to anything and even use some wildcards. P4DB accepts the perforce style wildcards ("..." for a series of any characters and "*" for any character except "/").
  Hint: P4DB lets you specify more than one file spec here. For example "//...*.c + //...*.h" will show changes in and *.c and *.h files. Multiple file specifications are separated with "<optional whitespace> + <optional whitespace>".
  
  
• Sometimes you may be interested in changes made by a specific user or group of users. Select "Changes by User or Group" on the main page. You will get a page with a list of users and a list of user groups (if any). Select the desired users and groups and click on OK.
  In windows Ctrl-Mouseclick will let you make an arbitrary selection in the list.
  
  
• A special case is when you are looking for changes with a specific keyword in the description. If you select "Search Changes by Descriptions" on the main page you will get a page where you can specify a file spec and a pattern to search for.
• There may be a "shortcut" (see below) that views the changes for the whole depot or the part of the depot you are interested in.

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.

• On the main page you can search for the file. Enter the file name in the "Search for file" field and press OK. You will now get a list of files that matches your search. Click on the desired file to view the file log for the file.
• You can browse the depot with the "Browse Deport" link on the main page. When the desired directory is found just click on the file name.

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.

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

Click on a subdir to descend to it.
3. 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.

• Each change is presented as a change number, date, user and client followed by the description.
• The change number is a link to view details about the change. There is a switch in the preferences (see Set Preferences) that makes the change show up in separate window.
• The user and client links to user and client views.
• If change number are mentioned in the description they are converted to a link to that specific change, e.g. "change 123" is converted to "change 123".
  P4DB parses the description and tries to find references to other changes to convert to links. The algorithm assumes english and can sometimes mistake other numbers in the description for references to changes.

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.

• The first part shows general statistics from the depot such as counters and number of users, clients etc.
• The second part shows submit and files statistics for the selected part of the depot
• The third part shows weekly submit rate for the selected part of the depot. Weeks are here defined as Sunday to Saturday.
• The fourth parts shows number of submits per user sorted by number of submits

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