Perforce 2005.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 is a software configuration management (SCM) tool that enables developers to version files, track changes to software development, manage releases, track defects, manage builds, and so on. Specifically:

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 copies of files cached on a proxy server.
Perforce offers release management facilities; you can use Perforce to track the file revisions that constitute 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 lifecycle management functionality; files can be kept in release branches, development branches, or in any sort of needed file set.
Perforce supports change review; users can be notified by email when particular files are changed.
Although a build management tool is not built into Perforce, Perforce offers a companion open source product called Jam. The Jam tool and Perforce are independent of each other; source files managed by Perforce are easily built by Jam.

Although Perforce was built to manage source files, you can use Perforce to manage any sort of content, including source code, binary files, other digital assets, HTML pages, formatted documents, or operating system configuration files.

Perforce Server and Perforce Client Programs

Perforce is based on a client/server architecture, in which users at client workstations are connected to a central server. Each user works on a client workstation; Perforce client programs on user workstations transfer files between the workstations and the Perforce server. Perforce client programs communicate with the server using TCP/IP.

Workstations running Perforce client programs can be distributed around a local area network, wide area network, dialup network, or any combination thereof. Perforce client programs 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. This program manages the shared file repository and keeps track of users, workspaces, and other Perforce metadata.

The Perforce Server must run on a UNIX, Mac OS X, or Windows machine.

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

Perforce supplies client software for UNIX, Linux, Windows, Mac OS X, and many other platforms.

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

When you use Perforce, you create, edit, and delete files on your own workstation in directories you specify to Perforce as client workspaces. You use Perforce commands to move files between the shared file repository (the depot) and your local workstation.

When you retrieve files from the depot into your client workspace, you can read, edit, and resubmit the files to the depot to make your changes accessible to other users. When a new revision of a file is stored in the depot, the old revisions of the file are preserved and are still accessible.

Files that you edit in your client workspace are aggregated and sent to the depot using changelists, which are lists of files and instructions that tell the depot what changes you made to those files. For example, one file might have been edited in your client workspace, another added, and another deleted. These file changes are sent to the depot in a single changelist, which is processed atomically: either all the changes are made to the files in the depot, or none are. This approach enables you to simultaneously update all files related to a bug fix or a new feature.

Each client workspace has its own client workspace view, which determines what files in the depot are mapped into its owner's 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 development branch. The Perforce Server tracks the state of all client workspaces, including the files in each client workspace, where they reside in the depot, and which files are being worked on by which users.

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 asks the user experiencing the conflict to perform a resolve of the conflicting files. The resolve process enables you to decide what needs to be done: should your file overwrite the other user's? Should your own changes be discarded? Or should the two conflicting files be merged into one? At your request, Perforce performs a three-way merge between the two conflicting files and the single file that on which both files were based. This process generates a merge file from the conflicting files that contains all the changes from both conflicting versions. You can also edit the merged file before submitting the it 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 more about labels, see Chapter 8, Labels.

Branching files

Suppose that one source file needs to evolve in two separate directions; perhaps one set of changes are required for UNIX support, and a second set of changes are required for OS X support. In such cases, two separately-evolving copies of the same files are necessary.

Perforce's Inter-File Branching^TM mechanism enables you to copy any set of files to a new location in the depot. The new file set, or codeline, evolves separately from the old codeline, 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 description of some change that needs to be made to a body of content or 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."

Perforce's job tracking mechanism links jobs to the changelists that implement the job. (A job represents work that is intended to be performed, a changelist represents work actually done.) A job can later be examined to determine if and when it was fixed, what files were modified to implement the fix, who fixed it, and whether the fix was 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. Perforce's job tracking functionality can be used as is, or you can integrate Perforce jobs with third-party job tracking systems by using P4DTI - Perforce Defect Tracking and Integration.

For more about jobs, please see Chapter 10, Job Tracking.

Change review

Perforce's change review mechanism enables 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 in Perforce is implemented by an external program, or daemon, which can be customized.

Perforce can be made to run external scripts when changelists are submitted or forms are changed. These scripts, called triggers, enable you to validate changelists and forms, start build processes or perform other tasks related to workflow.

To learn how to set up the change review daemon, integrate Perforce with third-party defect tracking systems, or develop your own custom daemons and triggers, see 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 which Perforce commands can be run by any particular user. Permissions can be granted or denied based on usernames, workstation IP addresses, and administrator-defined user groups.

Perforce protections are discussed in the Perforce System Administrator's Guide.

Other Perforce Client Programs

The Perforce Command-Line Client (p4) is not the only Perforce client program. Other Perforce client programs are available on the Perforce web site, including P4V, P4Win, and P4Web.

P4V

The Perforce Visual Client (P4V) is a graphical user interface to Perforce on Mac OS X, UNIX, Linux, and Windows. P4V provides quick and easy access to Perforce-managed files through a user interface that is consistent across many operating systems.

For more about P4V, see the product page at:

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

P4Win

The Perforce Windows Client (P4Win) provides a native Microsoft Windows user interface for all SCM tasks. Using the familiar Windows Explorer look and feel, P4Win shows your work in progress at a glance and provides easy access to Perforce tasks.

For more about P4Win, see the product page at:

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

P4Web

The Perforce Web Client (P4Web) turns any Web browser into a complete SCM tool. P4Web works with a Perforce Server at Release 99.2 or higher, and runs on UNIX, Linux, Mac OS X, and Windows platforms.

For more about P4Web, see the product page at:

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

Merge Tools

Interactive merge tools enable 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).

P4V

The Perforce Visual Client provides built-in merge capability for Mac OS X, UNIX, Linux, and Windows.

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 familiar three-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. You need only change an environment variable (such as P4MERGE or P4DIFF) to point to your 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 already have 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, what work that was done to resolve an issue, or to generate reports relating issues to files or codelines.

Activity in your Perforce depot - such as 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 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 and can be used with a Perforce Server on any platform at Release 2000.2 or higher. 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 enable developers to work with Perforce from within integrated development environments (IDEs) such as Visual Studio .NET, JBuilder, Eclipse, WebSphere Studio, CodeWarrior, and many more.

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 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 applications to work with documents under Perforce control.

For more about P4OFC, see:

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

P4EXP

The Perforce Plug-in for Windows Explorer (P4EXP) enables one-click access to Perforce operations (including add, edit, diff, view revision history, and more) from within the familiar Windows Explorer environment.

For more about P4EXP, see:

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