Perforce is a Software Configuration Management (SCM) system based on a client/server
architecture. Users of Perforce client programs connect to a Perforce server and use Perforce client programs to transfer files between the server's file repository and individual client workstations.
The Perforce server manages the master file repository, or depot
. There can be more than one depot per server. The depots contain every revision of every file under Perforce control. Perforce organizes files in depots into directory trees, like a large hard drive. Files in a depot are referred to as depot files
or versioned files
. The server maintains a database to track change logs, user permissions, and which users have which files checked out at any time. The information stored in this database is referred to as metadata
You use Perforce client programs to communicate with the Perforce server. Perforce client
programs enable you to check files in and out, manage conflicts, create development branches, track bugs and change requests, and more. Perforce client programs include:
|Integrations, or plug-ins
, that work with commercial IDEs and productivity software
Under Perforce, you never work directly on files in the depot. Instead, you use a Perforce
client program to manage a specially-designated area of your local workstation called a client workspace.
A client workspace contains a local copy of a portion of the depot.
When you retrieve files into a client workspace, your Perforce client program requests the
files from the Perforce server. To keep network traffic to a minimum, the Perforce server keeps track of what files you (and other users) have retrieved. Perforce client programs do not require a persistent connection to the Perforce server.
To use Perforce, you must set up your Perforce client program to connect to your
organization's Perforce server, tell your client program where your client workspace is located on your local hard drive, and tell your client program what files from the depot you plan to work with.
To work with Perforce, you must connect to a Perforce server. Your Perforce client
program communicates with Perforce servers over a TCP/IP connection. Each Perforce client program needs to know the address and port of the Perforce server with which it communicates.
The address and port are stored in the P4PORT
environment variable; depending on the Perforce client you are using, the process of configuring this variable is referred to as "setting your port
", or "connecting to the server
The documentation and the online help for your client program contain information on
how to set your port. If you don't know the port setting used for connecting to your organization's Perforce server, ask your Perforce administrator.
Perforce client programs manage files in a designated area of your local disk, called your client workspace
. Your client workspace is where you will be doing most of your work. You can have more than one client workspace, even on the same computer. The top level directory of any client workspace is called the client workspace root
To control where the depot files appear under your client workspace root, you must map
the files and directories on the Perforce server to corresponding areas of your local hard drive. These mappings constitute your client workspace view
Client workspace views consist of one or more lines, or mappings
. Each line in your workspace view has two sides: a "depot side
" that designates a subset of files within the depot and a "client side
" that controls where the files specified on the depot side are located under your client workspace root.
Creating a client workspace view doesn't transfer any files from the server to your
computer. The view only sets up the mapping that controls the relationship between the depot and your client workspace when files are transferred.
Other options for your Perforce client enable you to control the default behavior of
various operations within Perforce. For instance, you can control carriage return/linefeed translation for cross-platform development, or select a preferred text editor or merge utility for use within Perforce. To learn more about these and other options, see the documentation for your particular Perforce client program.
The Perforce server manages the depot, an archive of every version of every file in the
system. Your client workspace has a client workspace view that maps a subset of the depot's files to an area of your computer.
To populate your client workspace with the depot files, you must retrieve them from the
server. In Perforce, updating your workspace with files from the server is often referred to as syncing your workspace
. Other systems call this "refreshing", "getting the tip revision", or just "getting files".
When you sync your workspace, your Perforce client program uses your client workspace
view to map files in the depot to files in your client workspace, compares the result against the contents of your client workspace, and then adds, updates, or deletes files in your workspace as needed to bring your workspace contents in sync with the depot.
Perforce client programs manage file permissions in your workspace. By default, files
synced to your workspace are read-only, and become writable when you check them out for editing.
Perforce client programs also support options that enable you to retrieve earlier revisions
of files, or the revisions of files stored as of specified points in time, or sets of revisions that other users have tagged, or labeled
with a user-defined identifying label.
Perforce organizes files in the depot using directory hierarchies, like a large hard drive.
Perforce client programs use a set of rules that define the specification of files in the depot and in your workspace. Whether you are setting up the mapping (the client workspace view) between the depot and your workspace, loading your workspace with files from the depot, or checking files in or out, these rules for referring to files are common across all operating systems.
When you refer to files in Perforce, you can specify files relative to a client workspace root
("client syntax"), or to the top of the depot tree ("depot syntax"), or by absolute and or relative paths on your local file system ("local syntax").
Files specified in client syntax or depot syntax always begin with two slashes (//
), followed by the client workspace or depot name, and the full pathname of the file, relative to the client workspace root or top of the depot tree. Path components in client and depot syntax are always separated by forward slashes (/
), regardless of the component separator used by the local operating system.
For example, if the client workspace is named myworkspace
, and the workspace root is C:\Projects\working
, then the mapping specified by the view
maps the depot file //depot/main/src/file.c
into the client workspace as C:\Projects\working\module\file.c
Perforce uses the #
character to denote file revisions. File revisions in Perforce are sequentially-increasing integers, beginning from #1 for the first revision, and so on. The most recent revision of a file is the highest-numbered revision of that file on the server, and is called the head revision
. The revision you last synced to your workspace is called the have revision
. The zeroth revision of a file is called the null revision
, and contains no data.
When you work in Perforce, development branches (or codelines
) are represented as directory paths. Files in different codelines have their own set of revision numbers, starting at revision #1 and increasing upwards. The ancestry of files in different codelines is preserved in integration records
. To learn more about branching in Perforce, see Branching and integration
The indicator file.c#3/4
shows that you currently have revision #3 of file.c
synced to your workspace, and that the most recent revision of file.c
is #4. In contrast to other SCM systems, Perforce does not use perturbed version numbers (for instance, "revision 1.2.3
") to denote revisions of files in different development branches.
The syntax for the head, have, and null revisions (#head
, and #none
) is used in the Command Line Client and in the status window of graphical client programs. See the P4 User's Guide
files on the Macintosh,
By default, when anyone adds a file to the depot, Perforce attempts to determine the type
of the file automatically. You can change a file's type by opening it for edit as the new file type. If the file is already open for edit, you can reopen it as the different file type.
The six base file types can have modifiers (such as +w
, and others) applied that control such things as locking behavior, file permissions within a client workspace, or how revisions are stored on the server. The Command Reference
contains a complete list of file types and applicable modifiers.
The changelist is the basic unit of work in Perforce. The basic file editing operations
common to all SCM systems (such as editing files, adding files, deleting files, backing out changes, and checking in files) are performed in changelists.
After you have set up your workspace view and synced your workspace to the depot, you
can start working in Perforce. Before you can work on a file in your workspace, you must use your Perforce client program to open the file in a changelist. A changelist consists of a list of files, their revision numbers, the changes you have made to the files, and a description that you supply that describes the work you performed.
If you are working on a change to some software that requires changes to three files, open
all three files in one changelist. When you check the changelist back into the depot, other users will see your changelist linked to the changes made to all three files.
Perforce changelists are atomic change transactions
; if a changelist affects three files, then the changes for all three files are committed to the depot, or none of the changes are. Even if the network connection between your Perforce client program and the Perforce server is interrupted during changelist submission, the entire submit fails.
A changelist with changes not yet submitted to the depot is a pending changelist
. A changelist containing changes that have been committed to the depot is a submitted changelist
. Each changelist has a changelist number
(generated by Perforce), and a changelist description
(supplied by the user who performed the changes).
When you open a file in Perforce, the file is opened in a default changelist
. The default changelist is assigned a changelist number when you check its files back into the depot. You can partition your work in progress into multiple pending changelists. Pending changelists other than the default changelist are assigned numbers when you create the changelist. (A new number may be assigned to a pending changelist when you submit the changelist to the depot.)
To edit a file, you check out the file in a changelist. Your Perforce client program makes
the copy of the file in your client workspace writable, and informs the Perforce server that you have opened the file for editing.
For your changes to be available to other users, you must submit the changelist back to the
depot. After your changelist has been submitted, other users can sync their workspaces and obtain their own copies of your changes.
To add a file, you create a file in your client workspace and mark the file for add in a
changelist. Your Perforce client program determines the file's type (you can override this file type), and informs the Perforce server that you intend to add a file.
For your new file to be available to other users, you must submit the changelist with the
added file back to the depot. After the changelist has been submitted to the depot, other users can sync their workspaces and obtain their own copies of the new file.
To delete a file, you mark the file for delete in a changelist. The file is deleted from your
workspace immediately. Your Perforce client informs the server that you intend to delete a file, but the file is not marked as deleted in the depot until you submit the changelist.
After you have submitted the changelist to the server, other users see your file marked as
deleted. Local copies of the deleted file remain in other users' workspaces until those users sync their workspaces to the depot.
Deleted file revisions are never actually removed from the depot. You can always recover
older revisions of deleted files by syncing revisions that predate the file's deletion into your client workspace.
You can discard any changes you made
to a file in a changelist by reverting
the file. Reverting a file removes the file from its changelist and restores the copy of the file in your client workspace to the revision last synced to your workspace.
If you revert a file opened for edit or marked for delete, whatever version of the file you
last synced is restored to your workspace. If you revert a file marked for add, the file is removed from your changelist, but your local copy of the file remains in your client workspace.
When you are satisfied with the changes you have made to the files you opened and want
your work to be available to others, check your work back in to the depot by submitting
There is no such thing as a partially-submitted changelist. Changelist submission is an
atomic transaction; either all of the files in a changelist are submitted successfully, or none are.
When two users edit the same file at the same time, their changes can conflict. If your
changes conflict with earlier changes submitted by another user, Perforce requires that you resolve
the conflicting files and re-submit the changelist
. Because changelists are atomic transactions, until you resolve the conflict, none of the changes to any of the files in your changelist can appear in the depot.
The resolve process enables you to decide what needs to be done: should your file
overwrite the other user's? Should your own file be thrown away in favor of the other user's changes? Or should the two conflicting files be merged into one file? At your request, Perforce can perform a three-way merge between the two conflicting text files and the file from which the two conflicting files were derived.
Perforce helps teams to work concurrently. The conflict resolution and three-way merge
process enables multiple users to work on the same files at the same time without interfering with each other's work.
The three-way merge process for resolving file conflicts helps you to resolve conflicting
changes to text files, but is not necessarily meaningful for binary
files such as graphics or compiled code. If you are working on files where merges are not meaningful, you can lock such files to prevent others from making changes that conflict with your work.
For example, users working within an IDE that does not permit change resolution might
also want to lock the files they're working on so they don't have to switch to a Perforce client program to submit their work, and users working on digital assets might want to automatically classify all .gif
files as exclusive-open.
The p4 diff
and p4 diff2
commands produce output similar to that of the standard diff program included in UNIX and Linux systems. Other Perforce client programs (including P4V) include P4Merge, which provides a graphical view of file differences. For example:
The history of a file is represented by a series of file revisions, one per file. Each revision to
the file is associated with a changelist. You can compare files against the revision in your workspace or against any of the revisions stored in the depot.
This P4V screenshot shows that the depot holds three revisions of the file //depot/dev/main/jamgraph/gparticle.cpp
. The most recent revision, #3, was submitted in changelist 720.
The history of a directory is represented by a series of changelists. Directories do not have
individual revision numbers; rather, every changelist that includes at least one file is considered to be part of a directory's history.
Perforce has forms of syntax for referring to a file as it exists in the depot upon submission
of a numbered changelist, as tagged by a mnemonic label, or as of certain dates and times. These forms of syntax (@changelist
, or @date
, or #start,end
) are typically used only with the command line client, but they also appear in the status window of graphical client programs. See the P4 User's Guide
for more details.
To structure groups of related files by purpose, such as a new product or release, you use
branching. Branching is a method of managing changes between two or more sets of related files. Perforce's Inter-File Branching
mechanism enables you to copy any set of files to a new location in the depot by allowing changes made to one set of files to be copied, or integrated
, to the other. The new file set (or codeline
) evolves separately from the original files, but changes in either codeline can be propagated to the other by means of integration
Most software configuration management systems support some form of branching;
Perforce's mechanism is unique because it mimics the style in which users create their own file copies when no branching mechanism is available.
Suppose for a moment that you're writing a program and are not using an SCM system.
You're ready to release your program: what do you do with your code? Chances are that you'd copy all your files to a new location. One of your file sets becomes your release codeline, and bug fixes to the release are made to that file set; your other files are your development file set, and new functionality to the code is added to these files.
In Perforce's terminology, each set of files constitutes
, and copying a change from one set of files to another is called integration
. The entire process is called branching
Perforce organizes files in the depot using directory
hierarchies, like a large hard drive. When you make a new codeline, it appears in the depot as a subdirectory, such as //depot/dev/main/jam
for ongoing development work, //depot/release/jam/2.1
for release 2.1, and //depot/release/jam/2.2
for release 2.2.
To create a codeline or development branch, decide which files belong in the branch (the source files
), and integrate
those files into the new codeline to create the target files
. The Perforce server "opens the target files for branch/sync
" in a changelist.
Opening files for branch/sync
is just like opening them for add
, or delete
; the files are opened in a changelist, and your client workspace view must include the target files. Similarly, no changes are made to the depot until you submit the changelist. The atomic nature of changelists ensures that when you create a codeline, it contains all of the files you branched.
Without an SCM system, you might create a branch by copying the files from one
directory into another directory. The advantage of integration over copying the files and adding the copies to the depot in a new directory is that when you integrate files from one codeline to another, Perforce can track the connections between related files in an integration record
, facilitating easy tracking and propagation of changes between the two sets of files.
Integration also enables Perforce to perform a "lazy copy" of the files. When you branch
files, the server does not actually hold two copies of the files - it merely holds the source file and a pointer in the database records the fact that the branch to the target file has occurred. Lazy copies make branching a low-overhead operation; the server doesn't have to keep track of duplicate copies of files.
You can use integration to propagate changes between related codelines in much the same
way you create codelines. (Creating a codeline is equivalent to propagating a set of changes that make up the entirety of the source files into an empty set of target files.)
When you create a codeline, the target files are by definition empty; there is no possibility
your changes can conflict. When you propagate changes between existing codelines, conflicts can arise because conflicting changes may have been made in both the source and the target codelines.
In the example shown, the rel1.0
codeline was created by branching source files from //depot/main
into a target of //depot/rel1.0
in changelist 3567. Changelists 3574, 3582 and 3601 represent work performed in the release branch, and changelists 3575 and 3590 represent work performed in the main line.
In order to propagate work done in the release branch back into the main line, you
integrate from source files in //depot/rel1.0
, resolving any conflicting changes between work done in the release branch and work done in the main line.
The revisions in the target files in your client workspace are referred to as yours
. The revisions of the source files in the depot are referred to as theirs
. Where changes between these files do not conflict, the changes can be merged automatically. Where changes conflict, you must choose which changes are to be accepted into the file.
|Manual merge: Finally, there may be cases where the same lines in "theirs" and "yours"
have been changed. Such lines are said to conflict. When changes conflict, Perforce resolves as many differences as possible and produces a merged file containing conflict markers for manual resolution. You must either edit the merged file manually before submitting it, or accept the merged file with the conflict markers included, and fix the conflict in a subsequent changelist.
Perforce provides two mechanisms for branching: integrating using a file specification
, and integrating using a branch specification
For simple branch structures, you can manually specify the paths of the source and target
files, and integrate your source files to the target branch using file specifications. You must manually specify the source and target codelines every time you branch with a file specification.
For more complex branch structures, you can set up branch specifications
that enable you to reliably duplicate even the most complex branch structures. A branch specification holds a set of mapping rules (a branch view
) that controls how files in the source branch are integrated in the target branch. After you have set up a branch specification, you can perform the integration by using the branch specification to perform all of the integrations specified in the branch view.
For example, the branch specification
in the screenshot shows three mappings:.
The example screenshot shows a simple revision graph. The changes to the file
represented by revision #1 through revision #3 were integrated from the main codeline (//depot/dev/main/...
) into a release branch (//depot/release/jamgraph/1.0/...
) and into a development branch (//depot/dev/newfeatures...
Although Perforce's branching mechanism is relatively simple, the theory of branching
can be very complex. When should a branch be created? At what point should code changes be propagated from one codeline to another? Who is responsible for performing merges? These questions are common to every SCM system, and the answers are not simple.
A white paper on Inter-File Branching
that describes best practices for the use of Perforce's branching mechanism, as well as technical details, is available from:
Perforce includes a basic defect tracking system called jobs
. A Perforce job is a description of work to be done, such as a bug fix or a change request. Perforce's job tracking mechanism enables you to link one or more jobs to the changelists that implement the work specified in the jobs. Associating jobs with changelists helps teams know if and when work was completed, who performed the work, and what file revisions were affected by the work. Jobs linked to changelists are marked as closed when the changelist is submitted.
The types of information tracked by the jobs system can be customized; Perforce
administrators can add, change, or delete fields used by Perforce jobs. See the System Administrator's Guide
Perforce currently offers two independent platforms to integrate Perforce with third-party
defect tracking and workflow systems. Both platforms allow information to be shared between Perforce's job system and external defect tracking systems.
P4DTG, the Perforce Defect Tracking Gateway, is a closed-source integrated platform that
includes both a graphical configuration editor and a replication engine. For more information, see:
are sets of tagged file revisions, enabling you to reproduce specific groups of files within client workspaces. Labels differ from changelists in that a changelist number represents the state of all files in the depot at the time the changelist was submitted. Labels are used to tag arbitrary groups of files, even when those file revisions represent work that was submitted in more than one changelist.
Another difference between changelists and labels is that changelists are referred to by
Perforce-assigned numbers, while labels take names chosen by users. For example, you might want to tag the file revisions that compose a particular release with the label rel2.1
. At a later time, you can update the revisions tagged with rel2.1
to reflect fixes performed in subsequent changelists, and retrieve all the tagged revisions into a client workspace by syncing the workspace to the label.
Most Perforce client programs have options that enable you to specify a preferred text
editor or merge tool. For example, the Command Line Client uses the environment variables P4EDITOR
to invoke a preferred editor or merge tool.
Perforce provides a protection scheme to prevent unauthorized or inadvertent access to
the depot. The protections determine which Perforce commands can be run, on which files, by whom, and from which client workstations. Perforce administrators can set protections by using the p4 protect
command in the Perforce Command-Line Client, or by using the Administration Tool in P4V.
Perforce servers are licensed according to how many users they support. This licensing
information resides in a file called license
in the server root directory. The license
file is a plain text file supplied by Perforce Software. Without the license
file, the Perforce server limits itself to two users and five client workspaces.
For further information, see the System Administrator's Guide
, or contact technical support.
|Type p4 help
from the command line for help with the Command-Line Client
Copyright 2005-2009 Perforce Software.