Perforce 2003.1 User's Guide


<< Previous Chapter About This Manual	Table of Contents Index Perforce on the Web	Next Chapter >> Connecting to the Perforce Server

Chapter 1
Product Overview

Perforce facilitates the sharing of files among multiple users. It is a software configuration management tool, but software configuration management (SCM) has been defined in many different ways, depending on who's giving the definition. SCM has been described as providing version control, file sharing, release management, defect tracking, build management, and a few other things. It's worth looking at exactly what Perforce does and doesn't do:

Perforce offers version control: multiple revisions of the same file are stored and older revisions are always accessible.
Perforce provides facilities for concurrent development; multiple users can edit their own copies of the same file.
Perforce supports distributed development; users can work with files stored on a central server or with files replicated on a proxy server.
Some release management facilities are offered; Perforce can track the file revisions that are part of a particular release.
Bugs and system improvement requests can be tracked from entry to fix; this capability is known as defect tracking or change management.
Perforce supplies some lifecycle management functionality; files can be kept in release branches, development branches, or in any sort of needed file set.
Change review functionality is provided by Perforce; this functionality allows users to be notified by email when particular files are changed.
Although a build management tool is not built into Perforce, we do offer a companion open source product called Jam. The Jam tool and Perforce meet at the file system; source files managed by Perforce are easily built by Jam.

Although Perforce was built to manage source files, it can manage any sort of on-line documents. Perforce can be used to store revisions of a manual, to manage Web pages, or to store old versions of operating system administration files.

Perforce Server and Perforce Client Programs

Perforce has a client/server architecture, in which users at other computers are connected to one central machine, the server. Each user works on a client machine; at their command, a Perforce client program transfers files to and from the Perforce server. The client programs communicate with the server using TCP/IP.

The Perforce clients can be distributed around a local area network, wide area network, dialup network, or any combination of these topologies. Perforce clients can also reside on the same host as the server.

The following programs do the bulk of Perforce's work:

The Perforce Server (p4d) runs on the Perforce server machine. It manages the shared file repository, and keeps track of users, workspaces, and other Perforce metadata.

The p4d program must be run on a UNIX or Windows machine.

Perforce client programs (for instance, p4) run on Perforce client machines. Client programs send users' requests to the Perforce Server (p4d) for processing, and communicate with p4d using TCP/IP.

Perforce client programs can be run on many platforms, including UNIX, Linux, Windows, VMS, Macintosh, BeOS, and NeXT hosts.

This manual assumes that you or your system administrator have already installed both p4 and p4d. You'll find installation instructions in the Perforce System Administrator's Guide, also available at our Web site.

Moving files between the clients and the server

Users create, edit, and delete files in their own directories on client machines; these directories are called client workspaces. Perforce commands are used to move files to and from a shared file repository on the server known as the depot. Perforce users can retrieve files from the depot into their own client workspaces, where they can be read, edited, and resubmitted to the depot for other users to access. When a new revision of a file is stored in the depot, the old revisions are kept and are still accessible.

Files that have been edited within a client workspace are sent to the depot using a changelist, which is a list of files and instructions that tell the depot what to do with those files. For example, one file might have been changed in the client workspace, another added, and another deleted. These file changes can be sent to the depot in a single changelist, which is processed atomically: either all the changes are made to the depot at once, or none of them are. This approach allows users to simultaneously update all files related to a bug fix or a new feature.

Each client workspace has its own client view, which determines which files in the depot can be accessed by that client workspace. One client workspace might be able to access all the files in the depot, while another client workspace might access only a single file. The Perforce Server is responsible for tracking the state of the client workspace; Perforce knows which files a client workspace has, where they are, and which files have write permission turned on.

For basic information about using Perforce, see Chapter 3, Perforce Basics: Quick Start and Chapter 4, Perforce Basics: The Details.

File conflicts

When two users edit the same file, their changes can conflict. For example, suppose two users copy the same file from the depot into their workspaces, and each edits his copy of the file in different ways. The first user sends his version of the file back to the depot, and then the second user tries to do the same thing. If Perforce were to unquestioningly accept the second user's file into the depot, the first user's changes would not be included in the latest revision of the file (known as the head revision).

When a file conflict is detected, Perforce allows the user experiencing the conflict to perform a resolve of the conflicting files. The resolve process allows the user to decide what needs to be done: should his file overwrite the other user's? Should his own file be thrown away? Or should the two conflicting files be merged into one? At the user's request, Perforce will perform a three-way merge between the two conflicting files and the single file that both were based on. This process generates a merge file from the conflicting files, which contains all the changes from both conflicting versions. This file can be edited and then submitted to the depot.

To learn how to resolve file conflicts, see Chapter 5, Perforce Basics: Resolving File Conflicts.

Labeling groups of files

It is often useful to mark a particular set of file revisions for later access. For example, the release engineers might want to keep a list of all the file revisions that comprise a particular release of their program. This list of files can be assigned a name, such as release2.0.1; this name is a label for the user-determined list of files. At any subsequent time, the label can be used to copy its revisions into a client workspace.

For details about labels, see Chapter 8, Labels.

Branching files

Thus far, it has been assumed that all changes to files happen linearly, but this is not always the case. Suppose that one source file needs to evolve in two separate directions; perhaps one set of upcoming changes will allow the program to run under VMS, and another set will make it a Mac program. Clearly, two separately-evolving copies of the same files are necessary.

Perforce's Inter-File Branching^TM mechanism allows any set of files to be copied within the depot. By default, the new file set, or codeline, evolves separately from the original files, but changes in either codeline can be propagated to the other.

For details about branching, see Chapter 9, Branching.

Job tracking

A Job is a generic term for a plain-text description of some change that needs to be made to the source code. A job might be a bug description, like "the system crashes when I press return", or it might be a system improvement request, like "please make the program run faster."

Whereas a job represents work that is intended to be performed, a changelist represents work actually done. Perforce's job tracking mechanism allows jobs to be linked to the changelists that implement the work requested by the job. A job can later be looked up to determine if and when it was fixed, what files were modified to implement the fix, who fixed it, and whether the fix has been propagated to other codelines. The fields contained in your system's jobs can be defined by the Perforce system administrator.

Perforce's job tracking mechanism does not implement all the functionality that is normally supplied by full-scale defect tracking systems. Its simple functionality can be used as is, or it can be integrated with third-party job tracking systems through P4DTI - Perforce Defect Tracking and Integration.

To read more about jobs, please see Chapter 10, Job Tracking.

Change notification

Perforce's change review mechanism allows users to receive email notifying them when particular files have been updated in the depot. The files for which a particular user receives notification are determined by that user. Change review is implemented by an external program, or daemon, which can be customized.

Perforce can be made to run external scripts whenever changelists are submitted. These scripts, called triggers, allow changelists to be validated before they're submitted to the depot.

To learn how to set up the change review daemon, integrate Perforce with third-party defect tracking systems, or write your own daemons, consult the Perforce System Administrator's Guide.

Protections

Perforce provides a protection scheme to prevent unauthorized or inadvertent access to the depot. The protection mechanism determines exactly which Perforce commands are allowed to be run by any particular client.

Permissions can be granted or denied based on users' usernames and IP addresses, or can be granted or denied to entire groups of users. Because Perforce usernames are easily changed, protections at the user level provide safety, not security. Protections at the IP address level are as secure as the host itself.

We discuss protections in the Perforce System Administrator's Guide.

Other Perforce Clients

The Perforce Command-Line Client (p4) is not the only Perforce client program. Other Perforce client programs, including P4Win, the Perforce Windows Client, may be downloaded from the Perforce web site.

P4Win

The Perforce Windows Client provides a native Microsoft Windows user interface for all SCM tasks. Using the familiar Windows® Explorer look and feel, it shows you your work in progress at a glance and lets you point, click, drag, and drop your way through Perforce tasks.

For more about P4Win, see the product page at:

http://www.perforce.com/perforce/products/p4win.html

P4Web

The Perforce web client turns most any Web browser into a complete SCM tool. P4Web will work with a Perforce Server at Release 99.2 or newer, and runs on Unix, Macintosh, and Windows.

For more about P4Web, see the product page at:

http://www.perforce.com/perforce/products/p4web.html

Merge Tools

Interactive merge tools allow you to display the differences between file versions, simplifying the process of resolving conflicts that result from parallel or concurrent development efforts. Merge tools often use color-coding to highlight differences and some even include the option to automatically merge non-conflicting changes.

Perforce offers full support for both parallel and concurrent development environments. In situations where concurrent file check-out is not desirable, Perforce can be configured to restrict this capability to specific file types or file locations (for instance, management of digital assets in environments where concurrent development is not encouraged).

P4 resolve

Perforce's "p4 resolve" command includes built-in merge capability for the console environment.

P4WinMerge

P4WinMerge is Perforce's graphical three-way merge and conflict resolution tool for Windows. P4WinMerge uses the "3-pane" approach to display and edit files during the merge process.

P4WinMerge is a stand-alone Windows application; it does not require a Perforce Server when used by itself. However, when invoked from within a Perforce client program like the Perforce Command-Line Client, P4Win, or P4Web, a Perforce Server is necessary.

For more about P4WinMerge, see:

http://www.perforce.com/perforce/products/p4winmerge.html

Other merge utilities

Perforce is easily integrated with third-party merge tools and diff utilities. Users need only change an environment variable (such as P4MERGE or P4DIFF) to point to their merge tool of choice.

For more about using third-party merge tools with Perforce, see:

http://www.perforce.com/perforce/products/merge.html

Defect Tracking Systems

Perforce provides a number of options for defect tracking. In addition to providing basic built-in defect tracking, Perforce is integrated with several leading defect tracking systems. Activity performed by Perforce users can be automatically sent to your defect tracking system. Conversely, issues and status entered into your defect tracking system can be accessed by Perforce users.

Perforce jobs

Perforce's built-in defect tracking and reporting features are available to all Perforce users.

P4DTI integrations with third-party defect trackers

Although Perforce provides built-in defect tracking, some companies prefer to use the defect tracking system they've already got in place, or want to install a different defect tracker for use with Perforce.

Perforce Defect Tracking Integration (P4DTI) is an open source project specifically designed to integrate Perforce with other defect tracking systems by replicating Perforce jobs and changelist numbers to their equivalents in the other system.

P4DTI connects your defect tracking system to Perforce, so that you don't have to switch between your defect tracker and SCM tool and enter duplicate information about your work. P4DTI also links changes made in Perforce with defect tracker issues, making it easy to find out why a change was made, find the work that was done to resolve an issue, or generate reports relating issues to files or codelines.

Activity in your Perforce depot - enhancements, bug fixes, propagation of changes into release branches, and so forth - can be automatically entered into your defect tracking system by P4DTI. Conversely, issues and status entered into your defect tracking system - bug reports, change orders, work assignments, and so on, can be converted automatically to Perforce metadata for access by Perforce users. With P4DTI, you can integrate Perforce with any third-party defect tracking or process management software.

P4DTI uses Perforce's built-in "jobs" feature to mirror data in defect tracking systems. While Perforce jobs can be used without additional software for straightforward issue tracking, P4DTI lets you take advantage of third-party user interfaces, reporting tools, databases, and workflow rules to manage complex processes.

P4DTI runs on Unix and Windows. It can be used with a Perforce Server on any platform at Release 2000.2 or newer.

For more about using third-party defect tracking systems with Perforce, including a list of defect tracking systems for which P4DTI integrations have already been built, see:

http://www.perforce.com/perforce/products/defecttracking.html

Plug-Ins, reporting and tool integrations

IDE Plug-ins

Perforce IDE Plug-ins allow developers to work with Perforce from within integrated development environments (IDEs) such as Microsoft Developer Studio, Borland JBuilder, and Metrowerks CodeWarrior.

For more about Perforce IDE Plug-ins, see:

http://www.perforce.com/perforce/products/plugins-ide.html

P4Report and P4SQL

The Perforce Reporting System (P4Report) offers query and reporting capability for Perforce depots. P4Report also includes the Perforce SQL Command-Line Client (P4SQL). P4SQL can be used to execute SQL statements either interactively or using scripts.

Based on P4ODBC, the Perforce ODBC Data Source, P4Report can be used by ODBC-compliant reporting tools including Crystal Reports®, Microsoft® Access® and Excel®. P4Report can also be integrated with some defect tracking systems.

For more about P4Report and P4SQL, see:

http://www.perforce.com/perforce/products/p4report.html

P4OFC

The Perforce Plug-in for Microsoft Office (P4OFC) adds a "Perforce" menu to Microsoft Word, Microsoft Excel, and Microsoft Powerpoint. This menu provide easy access to common Perforce SCM commands, so that users never have to leave familiar office applications to work with documents under Perforce control.

For more about P4OFC, see:

http://www.perforce.com/perforce/products/plugins-ofc.html