Working in Perforce

Getting files from the service

The Perforce versioning service manages the depot, a shared repository that holds every version of every file in the system. Your workspace has a view that maps a subset of the depot's files to an area of your workstation.

To populate your workspace with the depot files, you must retrieve them from the versioning service. In Perforce, updating your workspace with files from the depot is often referred to as syncing your workspace. Other systems call this refreshing, getting the tip revision, or just getting files.

Syncing your workspace

When you sync your workspace, your Perforce application uses your workspace view to map files in the depot to files in your workspace, compares the result against the contents of your workspace, and then adds, updates, or deletes files in your workspace as needed to bring your workspace into sync with the depot.

Syncing your workspace retrieves a copy of the latest ("head") revision of each file. (Other versioning systems might refer to this as the "tip" revision.)

Syncing files to your workspace.

Perforce applications 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 applications 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.

Referring to files in Perforce

Perforce organizes files in the depot using directory hierarchies, like a large hard drive. Perforce applications use a set of rules that define the relationship between the location of files in the depot and in your workspace. Whether you are setting up the mapping (the 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.

Perforce syntax

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.



Depot syntax


Client syntax


Local syntax


When mapping depot files to the local hard drive, the workspace name is an alias for the workspace root.

A workspace specification.

For example, if the workspace is named myworkspace, and the workspace root is C:\Projects\working, then the mapping specified by the view:

//depot/main/src/... //myworkspace/module/...

maps the depot file //depot/main/src/file.c into the workspace as C:\Projects\working\module\file.c.

Using wildcards in views

You can use these wildcards when configuring workspace views in Perforce.





Matches all characters except slashes within one directory.

/src/*.c matches /src/file.c and /src/file2.c, but not /src/lib/file.c


Matches all files under the current working directory and all subdirectories.

/src/... matches all files and all subdirectories in and under /src

%1 - %%9

Positional specifiers that replace portions of filenames in views.

Mapping /%%1/%%2/... to /%%2/%%1/... maps /web/images /file.gif to /images/web/file.gif

These wildcards are also used when specifying files in the Command-Line Client. For more about Perforce syntax and wildcards, see the P4 Command Reference.

Referring to specific revisions of files

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 “Codeline Management”.

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 versioning systems, Perforce does not use perturbed version numbers (such as "revision 1.2.3 of file.c") to denote revisions of files in different development branches.


Refers to



The third revision of file.c

"Sync to the third revision of file.c".


The most recent revision of file.c stored in the depot; this is the head revision.

To get the latest versions of files from the depot, you sync your workspace to the head revision.


The revision of file.c last synced to your workspace; this is the have revision.

When you discard changes to a file, your Perforce application reverts the copy of the file in your workspace to the have revision.



The nonexistent, or null revision, of file.c.

When you use a Perforce application to remove files from your workspace, you are actually syncing the revision of the file in your workspace to the null revision.

Perforce syntax and the status bar

The syntax for the head, have, and null revisions (#head, #have, and #none) is used in the Command-Line Client and in the status window of graphical applications. See the P4 User's Guide for details.

What file types are supported?

Perforce file types include seven base file types.

  • text files,

  • binary files,

  • native apple files on the Macintosh,

  • Mac resource forks,

  • symbolic links (symlinks),

  • unicode (and utf16) files.

By default, when anyone adds a file to the depot, Perforce attempts to automatically determine the type of the file. 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, +x, +k, and others) applied that control such things as locking behavior, file permissions within a workspace, or how revisions are stored on the service. The P4 Command Reference contains a complete list of file types and applicable modifiers.

Working with files

The changelist is the basic unit of work in Perforce. The basic file editing operations common to all versioning systems (such as editing files, adding files, deleting files, backing out changes, and checking in files) are performed in changelists.

Using changelists

After you have set up your workspace view and synced your workspace to the depot, you can begin working in Perforce. Before you can work on a file in your workspace, you must 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.

Changelists serve two purposes:

  • to organize your work into logical units by grouping related changes to files together

  • to guarantee the integrity of your work by ensuring that related changes to files are checked in together

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.

How changelist numbers work

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

A workspace specification.

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

Editing files

To edit a file, you check out the file in a changelist. Your Perforce application makes the copy of the file in your client workspace writable, and informs the shared service 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.

Adding new files

To add a file, you create a file in your workspace and mark the file for add in a changelist. Your Perforce application determines the file's type (you can override this file type), and informs the service 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.

Deleting files

To delete a file, you mark the file for delete in a changelist. The file is deleted from your workspace immediately. Your Perforce application informs the versioning service 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, 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 workspace.

Discarding unwanted changes

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

Checking in files

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 the changelist.

Checking in files.

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.

Resolving conflicts

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.

An outline of the conflict resolution process.

Working concurrently

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.

Perforce supports two types of file locking. You can prevent files from being checked in with file locking and you can prevent file checkout with exclusive-open:

  • To prevent other users from checking in changes to a file you are working on, lock the file. Other users can still check out your locked file, but are unable to submit changelists that affect your locked file until you submit your changes. (To allow users to submit changelists that affect your locked file before you submit your work, unlock the file.)

  • To prevent a file from being checked out by more than one user at a time, use the +l exclusive-open filetype modifier. Files that have the +l filetype modifier can only be opened by one user at a time. Your Perforce administrator can use a special table called the typemap table to automatically specify certain file types as exclusive-open.

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 application to submit their work, and users working on graphics or video content might want to automatically classify all .gif or .mpg files as exclusive-open.

If you are editing



file (type)


Anyone can check out file and submit their changes.

If a user submits changes to file while you have file open, you must resolve your changes against their changes when you submit your changelist.

file (type)


Anyone can check out file, but no users can submit changes to file until you submit your changes to file, or until you remove the lock on file.

file (type+l)

unlocked or locked

Only one user at a time can have file open in a changelist. The status of the lock is irrelevant; no other users can submit changelists involving the file because no other users can check out the file.

For more about locking files, the exclusive-open filetype modifier, and the typemap table, see the P4 Command Reference and the Perforce Server Administrator's Guide: Fundamentals.

Comparing files

You can use Perforce to compare any two revisions of the same file, of any two files in the depot, or of files in the depot and their corresponding copies in your workspace.

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 diff2 output seen via the command line. The diff2 view seen in P4V.

Reviewing change histories of individual files

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.

The history of a file.

This P4V screenshot shows that the depot holds three revisions of the file //depot/Jamgraph/MAIN/src/gparticle.cpp. The most recent revision, #3, was submitted in changelist 362.

Reviewing change histories of groups of files

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.

The history of group of files.

This P4V screenshot shows that the most recent changelist that affected at least one file in //depot/Jamgraph/MAIN/src was changelist #1969.

Perforce syntax and the status bar

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, @labelname, or @date, or #start,end) are typically used only with the command-line client, but they also appear in the status window of other Perforce applications. See the P4 User's Guide for more details.