<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.5 [en] (X11; I; Linux 2.0.35 i686) [Netscape]">
<meta name="Author" content="holtdl@yahoo.com">
<meta name="Description" content="Information on how to use P4DB">
<title>HELP file for P4DB</title>
</head>
<body>
<center><font size=+2><b>Help for P4DB</b></font></center>
<p>
<center><font size=+2><b>The Perforce Depot Browser</b></font></center>
<p>
<font size=+2><b>Overview</b></font>
<br>
P4DB is a browser that allows you to explore a Perforce
source-code repository
(“depot”). P4DB lets you list the source-tree
directories, examine files, display information about changes, do
“diff”s of file revisions, labels,
etc.
P4DB does not allow you to affect the depot
—
you can use it to display information, but you can't change
anything with it.
<p>
<font size=+1><b>The P4DB Home Page</b></font><br>
<a href=#HI>Header Information</a><br>
<a href=#BDT>Browse Depot Tree</a><br>
<a href=#PC>Pending Changes</a><br>
<a href=#LB>List Branches</a><br>
<a href=#LL>List Labels</a><br>
<a href=#LU>List Users</a><br>
<a href=#SFF>Search for file</a><br>
<a href=#VCF>View changes for file</a><br>
<a href=#VCN>View change number</a><br>
<a href=#BDR>Browse a different repository</a><br>
<a href=#LCB>List Changes by Branch</a><br>
<a href=#LOF>List Opened Files</a><br>
<a href=#LCU>List Changes by User</a><br>
<a href=#GH>Get Help</a><br>
<a href=#GSR>The Great Submit Race</a><br>
<a href=#ML>Mail</a><br>
<font size=+1><b>General Information About Viewing Files and File Data</b></font><br>
<a href=#DCF>Displaying the Contents of a File</a><br>
<a href=#DFD>Displaying File Data</a><br>
<font size=+1><b>Frequently Asked Questions</b></font><br>
<a href=#FAQ>The P4DB FAQ</a><br>
<br>
<table width=100% border=0>
<tr valign=center>
<td width=5%>
<img height=22 src=../icons/hand_point3.gif>
<td width=95%>
The term <i>Legend</i> refers to the gray area at the top of each page.
<td width=5%>
</table>
<p>
<a name=HI><b><font size=+1>Header Information</font></b></a>
<br>
<b>Current change number</b> is the number of the most recent change that was
submitted. This number is also the default value for the
<a href=#VCN>View change number</a>
form
—
to see the details for the latest change, click on the gray area of the
<b>View change number</b>
form.
<p>
<b>Host</b> is the name of the machine the daemon for the P4 server you
are accessing is running on;
<b>Port</b> is the port number the daemon is listening on.
<p>
<a name=BDT><b><font size=+1>Browse Depot Tree</font></b></a>
<br>
Clicking on <b>Browse Depot Tree</b> will display the
<i>Depot Tree Browser</i>
page, which allows you to
“walk the source-tree”.
If the P4 source repository has more than one depot,
accessing the
<i>Depot Tree Browser</i>
page from the P4DB homepage will display a list of the
depots. Selecting a depot from this page will then display
a list of the subdirectories and files at the top of that
depot. If the repository has only one depot,
accessing the
<i>Depot Tree Browser</i>
page from the P4DB homepage will display a list of the
subdirectories and files at the top of the depot.
As indicated in the Legend
for the
<i>Depot Tree Browser</i>
page, clicking on a subdirectory listed on the page
will display a list of the
subdirectories and files at that directory level, and so on.
If files are listed at the
current directory level, clicking on a filename will display the
<i>File Log</i>
page, which contains the P4 filelog (revision history) information for
that file.
See the
<a href=#FLP>File Log Page</a>
section for details.
<p>
The <b>Back to</b> line on the
<i>Depot Tree Browser</i>
page allows you to
climb back up the directory tree without having
to do it a directory at a time. You can click on any one of the
directory elements and go directly to that directory.
For example, if you are currently at the
<tt>//depot/main/docs/intranet/arch</tt>
directory level and want to return to <tt>//depot/main</tt>, click on the
<b>/main</b> element on the <b>Back to</b> line.
<p>
The
<i>Depot Tree Browser</i>
Legend also contains two
“action”
options.
The
<b>View changes for all files below this point</b>
option will display a list of all the changes that have been
submitted on files in the current directory and on any files in any
subdirectories of the current directory. Selecting this option will
display the
<i>Change History</i>
page.
As the Legend on the
<i>Change History</i>
page indicates, clicking on the change number
will display the
<i>Change <tt><number></tt></i>
page, which contains the details
of that change.
Refer to the section on
<a href=#VCN>View change number</a>
for more information regarding the
<i>Change <tt><number></tt></i>
page.
<p>
The <b>Hide deleted files</b> option is a
“toggle”
that will either hide or
show deleted files. If the current display includes files that have a
line through them, this indicates these files have been
“deleted”
(via a
<b><i>p4 delete</b></i>).
To see the files in this directory without
the deleted files being shown, click on
<b>Hide deleted files</b>.
The files
that had been displayed with lines through them will no longer appear,
and the
“action”
option will change to
<b>Show deleted files</b>.
Click on this option again to redisplay the deleted files.
<p>
<b><i>Note:</i></b>
The
“toggle”
will stay in its current
state until you click on it again. That is,
if you click on another directory, and
“hiding deleted files”
is the current state (the Legend contains
<b>Show deleted files</b>),
then any subsequent directory
listings will not show (<i>i.e.</i>,will be
“hiding”)
deleted files until you
“toggle”
the state by clicking on
<b>Show deleted files</b>.
<p>
<a name=PC><b><font size=+1>Pending Changes</font></b></a>
<br>
Clicking on <b>Pending Changes</b> will display a list of the changes,
for all current P4 users,
that have been assigned a P4 change number but have not yet been submitted.
If you want to see only the pending
changes for a specific user, you can use the
<b><i>View pending changes only for</i></b>
form at the top of the
<i>Pending Changes</i>
page.
A list of all the current P4 users is provided
—
click on either the
“down arrow”
or inside the box to get the list, then
select the name of the user you want to see pending changes for, and click
on <b>Go</b>.
<p>
As indicated in the Legend for the
<i>Pending Changes</i>
page, clicking on a pending change number will
display the
<i>Change <tt><number></tt></i>
information page, which contains the
details of that pending change.
(Refer to the section on
<a href=#VCN>View change number</a>
for more information regarding the
<i>Change <tt><number></tt></i>
page.)
<p>
<a name=LB><b><font size=+1>List Branches</font></b></a>
<br>
Clicking on <b>List Branches</b> will display a list of all the branches
that have been created for this repository,
along with information about each branch.
As indicated in the Legend on the
<i>P4 Branches</i>
page, clicking on the name of the owner of the branch
will display the P4 user information.
Clicking on the left-side mapping path
on the <b>View</b> line
will display a list of all the changes that have been put through for
all the files in and below that directory.
Clicking on the right-side mapping path
will display a list
of all the changes that have been put through for the branch.
<p>
<a name=LL><b><font size=+1>List Labels</font></b></a>
<br>
Clicking on <b>List Labels</b> will display a list of all
the labels that have been created for this repository,
along with the date the label was created
and the label description.
As the Legend for the
<i>P4 Labels</i>
page indicates, clicking on the label name will display the
<i>Label Information</i>
page,
which contains the full label specification, Legend
“action”
options, and forms that allow you
to:
<blockquote>
<li>
diff the current label against another label, with options to limit the diff
<li>
view the changes for the current label, while excluding another label
<li>
search for files in this label
</blockquote>
<p>
The
<b>View changes for <i>label_name</i></b> Legend
“action”
option allows you to display a list of all the changes that
have been submitted for files included on this label.
The
<b>List files in <i>label_name</i></b>
option allows you to display a list of all the files that are included
on this label.
<b><i>Caution</i>:</b>
Some labels can contain many thousands of filenames, so getting
a full list of the files on a label can be fairly slow and
local-resource intensive.
<p>
The
<b>Diff with label</b>
form allows you to select a label to diff against the current one.
The
<b>Show files that</b>
form allows you to limit the files displayed from the diff to:
<blockquote>
<li>
just those files that
<b>are not modified</b> between the two labels (files
that exist on both labels, and at the same revisions);
<li>
just those files that
<b>are modified</b>
between the two labels (files
that exist
on both labels, but at different revisions);
<li>
just those files that
<b>differ</b> between the two labels (files that exist
only on one or the other label, but not both).
</blockquote>
You can combine these options in any way you choose. For example,
to see a list of all the files in common between the two labels
but that are at different revisions, as well as all the files that exist
on only one or the other of the labels, turn on both the
<b>are modified</b>
and the
<b>differ</b>
options. (This is the default setting when you first access this page.)
<p>
If you turn off all these options, the
<i>Label Diff</i>
page will display only the label specifications for the two labels,
a file count for each label, and a count of the number of files the
two labels have in common, including a count of those at the same
revision numbers.
<p>
The
<b>View changes for <i>label_name</i> excluding label</b>
form allows you to display a list of all the changes that
have been submitted for the files on the current label,
<i>except</i>
those
changes that also occur on the excluded label.
<p>
The
<b>Search in label for</b>
form allows you to search the label for files that match
the pattern you specify. The pattern can be either a specific
filename, or it can be specified using the P4 wildcards
“<b>…</b>” and “<b>*</b>”.
(Refer to the
<a href=#SFF>Search for file</a>
section for more details regarding using wildcards.)
<p>
<a name=LU><b><font size=+1>List Users</font></b></a>
<br>
Clicking on
<b>List Users</b>
will display the list of all current P4 users.
As indicated in the Legend for the
<i>P4 Users</i>
page,
clicking on the email address will generate a mail message to that user.
To send mail to all the current P4 users,
select the
<b>Mail all users</b>
Legend
“action”
option.
<p>
Clicking on the user name will display the
<i>P4 User Information</i>
page,
which contains the user information as well as
a list of all the files currently opened by that user.
As the Legend for the
<i>P4 User Information</i>
page indicates, clicking on the email address will
generate a mail message to that user. Clicking on the
filename of an opened file will display the filelog
for that file.
The Legend also contains an
“action”
option that allows you to display a list of the user's clients.
<i>Note</i>:
Because of an oversight in the output of the
<b><i>p4 clients</i></b>
command, generating a list of a clients owned by a particular
user is a somewhat lengthy process, so expect it to take a
minute or two to complete. Selecting the
<b>Display user's clients</b>
option will redisplay the
<i>P4 User Information</i>
page with the list of clients included. Note that the Legend
now also indicates that clicking on a client name will display
the P4 client information.
<p>
<a name=SFF><b><font size=+1>Search for file</font></b></a>
<br>
This form allows you to search the source-tree for files that match
the pattern you specify. The pattern can be either a specific
filename, or it can be specified using the P4 wildcards
“<b>…</b>” and “<b>*</b>”.
For example:
<blockquote>
<li>
To find all the files named
<tt>build.jam</tt>
under the
<tt>//depot/main</tt>
directory and all its subdirectories, enter:
<blockquote>
<tt>//depot/main/...build.jam</tt>
</blockquote>
<li>
To find all the
<tt>build.jam</tt>
files that live only in a direct subdirectory of
<tt>//depot/main/java</tt>,
enter:
<blockquote>
<tt>//depot/main/java/*/build.jam</tt>.
</blockquote>
<li>
To find all the files throughout the entire repository that end with
<tt>.java</tt>,
enter:
<blockquote>
<tt>//...*.java</tt>
</blockquote>
<li>
To find all the files that live in directories with
“doc”
in the directory name, enter:
<blockquote>
<tt>//.../*doc*/...</tt>
</blockquote>
</blockquote>
The results of the search are displayed on the
<i>Search Results</i>
page, which includes the number of files found that match the pattern,
the list of files found, and, if the search resulted in more than
one file being found, a
<b>View diff between</b>
form that allows you to diff any two of
the files listed. The default values for this form
are the first and second files listed.
<p>
<a name=VCF><b><font size=+1>View changes for file</font></b></a>
<br>
This
form allows you to display the changes for files that match
the pattern you specify. The pattern can be either a specific
filename, or it can be specified using the P4 wildcards
“<b>…</b>” and “<b>*</b>”.
(Refer to the
<a href=#SFF>Search for file</a>
section for more details regarding using wildcards.)
<p>
<a name=VCN><b><font size=+1>View change number</font></b></a>
<br>
This form allows you to specify a change number to see the details
of that particular change. The default value for this form is the
change number of the most recently submitted change.
To see the details for the default change number, click on the gray
area of the
<b>View change number</b>
form.
<p>
The details of the change are displayed on the
<i>Change <tt><number></tt></i>
page. This page contains:
<blockquote>
<li>
the name of the P4 user who submitted the change,
<li>
the name of the P4 client that was used,
<li>
the date the change was submitted (or last modified),
<li>
the description of the change, and
<li>
the P4 Jobs the change fixed (if implemented).
</blockquote>
Below this is the list of the files that comprised the change.
<p>
As the
Legend for this page indicates, clicking on the user's name will display
the P4 user information. Clicking on the action will display the diff
the change generated for that file. Clicking on the revision number will
display the contents of that file at that revision. Clicking on the
filename will display a P4 filelog for that file.
<p>
If more than one file was submitted for the change, the
<b>Diff all files in change</b>
option will be displayed at the end of the list of files.
Selecting this option will display the
<i>Diff Output</i>
page, which will contain the diffs for each file included
in the change.
<p>
Also included on the
<i>Change <tt><number></tt></i>
page, directly below the legend, is the option to either
go to the previous change, or the next change (unless
this change is the latest submitted change).
<p>
<a name=BDR><b><font size=+1>Browse a different repository</font></b></a>
<br>
This form allows you to browse a different repository
by entering either a new host name or new port number,
or both, in order to change the P4 server you are accessing.
For example,
if you want to access the source repository at Perforce that is
available to the public, enter
<tt>public.perforce.com</tt>
in the left-hand side of the form.
If the port number, in the right-hand side of
the form, is already set to
<tt>1666</tt>,
click on
<b>Go</b>; otherwise, first change
the port number to
<tt>1666</tt>,
then click on
<b>Go</b>.
<p>
<a name=LCB><b><font size=+1>List Changes by Branch</font></b></a>
<br>
Clicking on
<b>List Changes by Branch</b>
will display a list of all the
branches in the repository. As indicated in the Legend on the
<i>Changes by Branch</i>
page, clicking on one of the branch names
will display a list of all the changes that have been submitted
into that branch. To see a list of only those changes submitted
by a specific user, use the
<b><i>View branch changes only for</i></b>
form at the top of the page.
A list of all the current P4 users is provided
—
click on either the
“down arrow”
or inside the box to get the list, then
select the name of the user you want to see pending changes for, and click
on <b>Go</b>.
<p>
<b><i>Note:</i></b>
If you know the branch path,
you could also see the branch changes by clicking on
<b>Browse Depot Tree</b>,
then working your way through directories on the
<i>Depot Tree Browser</i>
pages to get to the branch path, and selecting the
<b>View changes for all files below this point</b>
option to see the same list of changes
—
<b>List Changes by Branch</b>
is offered as a short-cut, as well as offering the option to
list branch changes only for a specific user.
<p>
<a name=LOF><b><font size=+1>List Opened Files</font></b></a>
<br>
Clicking on
<b>List Opened Files</b>
will display a list of all the currently opened (via a
<b><i>p4 add</i></b>,
<b><i>p4 delete</i></b>,
or
<b><i>p4 edit</i></b>
command), for all users, in all clients. To see only the opened
files for a specific client, use the
<b><i>View opened files only for client:</i></b>
form at the top of the list of files.
<p>
As indicated by the Legened for the
<i>Opened Files</i>
page, clicking on the revision number will display the contents
of that file at that revision, clicking on the user name will
display the P4 user information for that user, clicking on the
client name will display the P4 client information for that client,
and clicking on the filename will display the filelog for that file.
For any file that has a change
<i>number</i>
(rather than
<tt>(default)</tt>)
in the
<b>Change</b>
column, you can click on that change number to see the details
of that (pending) change.
<p>
<a name=LCU><b><font size=+1>List Changes by User</font></b></a>
<br>
Clicking on
<b>List Changes by User</b>
will display a list of all the
current P4 users. As indicated in the Legend on the
<i>Changes by User</i>
page, clicking on one of the user names
will display a list of all the changes that have been submitted
by that user. As indicated by the Legend on the
<i>Change History</i>
page, click on a change number to display the
<i>Change <tt><number></tt></i>
page and see the details of that change.
(Refer to the section on
<a href=#VCN>View change number</a>
for more information regarding the
<i>Change <tt><number></tt></i>
page.)
<p>
<a name=GH><b><font size=+1>Get Help</font></b></a>
<br>
Click on
<b>Get Help</b>
to access this help page.
<p>
<a name=GSR><b><font size=+1>The Great Submit Race</font></b></a>
<br>
Have fun!
…
<p>
<a name=ML><b><font size=+1>Mail</font></b></a>
<br>
If you have any questions or concerns about the P4 source tree
(<i>e.g.</i>, some
branch looks wrong, is obsolete, a file isn't showing up where it should be,
etc.), click on
<b>P4 Administrator</b>
to send mail.
<p>
If you have questions, suggestions, problems, bugs to report, etc. about
P4DB itself, click on
<b>P4DB Administrator</b>
to send mail.
<p>
<a name=DCF><font size=+1><b>Displaying the Contents of a File</b></font></a>
<br>
<b><i>Revision Number</i></b>
<br>
On any page that includes a revision number for a file, click on the
revision number to see the text of the file at that revision. The
contents of the file will be displayed on the
<i>File View</i>
page. The Legend for this page varies, depending on the type of
file being displayed.
Some types of files can be displayed as their
end-product rather than their source.
The following file extensions are treated by P4DB
as specially viewable files:
<blockquote>
<li>
.html and .htm for HTML files
<li>
.gif for GIF files
<li>
.jpeg and .jpg for JPEG files
<li>
.doc for MS-Word files
<li>
.dot for MS-Word Template files
<li>
.ppt for MS-PowerPoint files
<li>
.pdf for PDF files
<li>
.rtf for RTF files
</blockquote>
<p>
For example, if you are viewing
the source-file for an HTML file, the Legend will contain four
“action”
options. Select the
<b>View HTML file using browser</b>
option to display the file
as it would appear if you brought it up in your
browser as a URL.
Select the
<b>About Links and the HTML File Viewer</b>
option to
display a short explanation of how links are handled
by the HTML file viewer.
<p>
For all except binary files, you can click on the
<b>View line-by-line history trace</b>
option to display the file
as output from the
<b><i>p4pr</i></b>
utility, which produces an audit of the file,
showing for each line the change number,
who made the change, and at
what revision the line was changed.
<p>
All file types offer the
the
<b>Download file</b>
“action”
option. Select this option to save the file locally.
<p>
<a name=DFD><font size=+1><b>Displaying File Data</b></font></a>
<br>
<b><i>Change Number</i></b>
<br>
On any page that includes a change number for the file, click on the
change number to see the details of that change.
<p>
<b><i>Action</i></b>
<br>
On any page that includes an action for the file, click on the action
to see the diffs that action generated.
<p>
<b><i>Filename</i></b>
<br>
On any page that includes a filename, click on the filename to see a
P4 filelog (revision history) for that file.
<p>
<a name=FLP><b><i>The </i>File Log<i> Page</i></b></a>
<br>
The
<i>File Log</i>
page displays the revision history of a file.
As the Legend for the
<i>File Log</i>
page indicates, clicking on a change number will display the
details of that change. Clicking on an action will display the
diffs that were generated by that change.
Clicking on a revision number will display the contents of the
file at that revision. Clicking on the user who submitted the
change will display the P4 user information for that user.
<p>
Also included in the
<i>File Log</i>
page Legend are two
“action”
options. The
<b>Changes</b>
option will display the
<i>Change History</i>
page, which will contain a list of all the changes that have
been submitted that included this file.
The
<b>List labels</b>
option will redisplay the
<i>File Log</i>
page, additionally displaying information
about any labels this file is included on.
<p>
The
<i>File Log</i>
page also includes a form that allows you to diff two revisions
of the file. The default setting for the
<b>Show diff between revision</b>
form is the latest revision and the next-to-latest revision.
To change the revision numbers, click on either the
“down arrow”
or inside the box to get the list of revision numbers, then
click on
<b>Go</b>.
<p>
<a name=FAQ><font size=+1><b>P4DB FAQ</b></font></a>
<br>
At this point, there isn't one. If you have any questions about how to
use P4DB that haven't been covered by this help page, you are welcome
to send mail to the P4DB Administrator
—
click on
<b>P4DB Administrator</b>
on the
<b>Mail</b>
line at the bottom of any P4DB page.
The FAQ for P4DB will grow as questions about it come up.
<p>
</body>
</html>