Perforce 2000.1 Command Line User's Guide (2000.1.ug.3)
<< Previous Chapter
About This Manual
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Connecting to the
Perforce Server


Chapter 1
Perforce Concepts
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 excels at all file management functions. Although Perforce was built to manage source files, it can manage any sort of on-line documents. It can be used to store revisions of a manual, to manage Web pages, or to store old versions of operating system administration files. Its branching functionality, which allows copies of files to evolve separately from the files they were copied from, is unparalleled in the industry. And Perforce is extremely fast.

Note

You don't need to read the rest of this chapter if you don't want to. All the material discussed here is also covered in the "how-to" chapters, which comprise the rest of the manual. This chapter is provided as a guide to what Perforce does, without the details of how to do it.

Perforce Architecture


Perforce has a client/server architecture, in which many computers, called clients, are connected to one central machine, the server. Each user works on a client; at their command, files they've been editing are transferred to and from the server. The clients communicate with the server via TCP/IP.

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

Two programs do the bulk of Perforce's work:

The p4d program must be run on a UNIX or Windows/NT host.

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

This manual assumes that either you or your system administrator has already installed both p4 and p4d. You'll find instructions for this in our System Administrator's Guide, available at our Web site.

Moving Files Between the Clients and the Server


Users create, edit, and delete files in their own directories on the clients; 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 via 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 might 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 allows problem fixes that span multiple files to be updated in the depot at exactly the same time.

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

The basics of using Perforce are covered in Chapters 3 and 4.

File Conflicts


When two users edit the same file, it is possible for their changes to 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; subsequently, 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: the merge file contains all the changes from both conflicting versions, and this file can be edited and then submitted to the depot.

To learn how to resolve file conflicts, see Chapter 5.

Labeling Groups of Files


It is often useful to mark a particular set of file revisions for later access. For examples, 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 single mnemonic name, like 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 the old file revisions into a client workspace.

You'll learn about labels in chapter 8.

Branching Files


Thus far, it has been assumed that all changes of 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 BranchingTM 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.

We're particularly proud of Perforce's branching mechanism. Most SCM systems allow some form of branching, but Perforce's is particularly flexible and elegant.

The mechanism of Inter-File Branching is covered in chapter 9.

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, which file revisions implemented the fix, and who fixed it. 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 functionality normally supplied by full-scale defect tracking systems. Its simple functionality can be used as is, or it can be integrated with a full-scale job tracking system with a scripting language like Perl or Python.

To read more about jobs, please see chapter 10.

Change Review, Daemons, and Triggers


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

External scripts can be run automatically by Perforce whenever changelists are submitted. These scripts, called triggers, allow files to be validated before they're submitted to the depot.

The change review daemon is not covered in this guide. To learn how to set up the change review daemon, or how to write your own daemons, you'll need to consult our 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. Since 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 our System Administrator's Guide.


Perforce 2000.1 Command Line User's Guide (2000.1.ug.3)
<< Previous Chapter
About This Manual
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Connecting to the
Perforce Server

Please send comments and questions about this manual to [email protected].
Copyright 1997, 1998, 1999, 2000 Perforce Software. All rights reserved.
Last updated: 10/09/00