Perforce 2005.1 User's Guide
<< Previous Chapter
Connecting to the
Perforce Server

Table of Contents
Perforce on the Web
Next Chapter >>
Perforce Basics:
The Details

Chapter 3
Perforce Basics:
Quick Start

This chapter teaches basic Perforce usage. You'll learn how to set up your workspace, populate it with files from the common file repository (the depot), edit these files and submit the changes back to the repository, back out of any unwanted changes, and use some basic Perforce reporting commands.

This chapter gives a broad overview of these concepts and commands; for details, see Chapter 4, Perforce Basics: The Details.

Underlying concepts

Working in Perforce is simple: you create, edit, and work on files a set of directories on your local machine. These directories make up your client workspace. You use Perforce commands to move files to and from the shared file repository, called the depot. Other Perforce users retrieve files from the depot into their own client workspaces, where they can read, edit, and submit their changes 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 remain accessible.

Perforce was written to be as unobtrusive as possible, so that few changes to your normal work habits are required. You work on files in your own directories using your editor or IDE of choice; Perforce commands supplement your normal work actions instead of replacing them.

Perforce commands are always entered in the form p4 command [arguments].


Many p4 commands display a form for editing in a standard text editor. You can specify your text editor of choice by setting the P4EDITOR environment variable.

Setting up a client workspace

To move files between the depot and a client workspace, the Perforce server requires two pieces of information:

Naming your client workspace

To name your client workspace, or to use a different workspace, set the environment variable P4CLIENT to the name of the client workspace.

Different operating systems and shell have their own methods of setting environment variables. See "Setting and viewing environment variables" on page 148 for details.

Describing your client workspace to the Perforce server

To define the new client workspace that you specified by setting P4CLIENT, or to edit an existing client workspace, use the p4 client command. Enter:

Typing p4 client brings up the client definition form in a text editor. After you have filled out the form and exited the text editor, you can use Perforce client programs to move files between the depot and your client workspace.

The p4 client form contains a number of fields; at this point, the important fields are the Root: and View: fields:



Your client workspace root is the topmost subdirectory of your client workspace. Set your client workspace root to a directory under your control; you will be doing most of your development work on files located in your client workspace.


The client workspace view determines which files and directories in the depot are mapped to your client workspace, and where the files appear beneath your client workspace root.


In the text forms used by Perforce, field names always start in the leftmost column of text, and field values are indented with tabs or spaces. Perforce requires that there be at least one space or a tab prior to the contents of a form field.

In the p4 client form, the read-only Client: field contains the string stored in the P4CLIENT environment variable. The Description: is a free-form text field where you can add a description of the workspace. The View: field describes the relationship between files in the depot and files in the client workspace. To use Perforce properly, it is crucial to understand how views work. Views are discussed in greater detail in "Mapping Depot files to your Client Workspace" on page 38.

Creating a client specification has no immediate visible effect; no files are created when a client specification is created or edited. The client workspace specification merely defines where files are located when you populate your workspace with files from the server.

Copying depot files into your workspace

To retrieve files from the depot into a client workspace, use the p4 sync command.


If you've just installed a Perforce server for the first time, p4 sync won't do anything, because an empty depot contains no files to copy to client workspaces.

If you have just installed a Perforce server, use p4 add, as described in "Adding files to the depot" on page 29, to populate the depot by copying files from your client workspace to the depot.

The p4 sync command maps depot files through your client workspace view, compares the result against the contents of your client workspace, and then adds, updates, or deletes files in your workspace as needed to bring the contents of your workspace into sync with the depot.

If a file exists within a particular subdirectory in the depot, but that directory does not yet exist in your client workspace, the directory is created in the client workspace when you run p4 sync. If a file in your client workspace has been deleted from the depot, p4 sync removes the file from your client workspace.

By default, p4 sync updates your entire client workspace. To limit the update to only a portion of your client workspace, you can supply filenames or wildcards to p4 sync.

Updating the depot with files from your workspace

Any file in your client workspace can be added to, updated in, or deleted from the depot in a two-step process:

  1. You add information about changes to files in your client workspace to a changelist by using the commands p4 add filenames, p4 edit filenames, or p4 delete filenames. A Perforce changelist is a list of files and operations (such as adding a new file to the depot, editing an existing file, or deleting a file from the depot) to be performed in the depot.

  2. You use the p4 submit command to commit your changes to the depot. When the p4 submit command successfully completes, the changes to the files in your workspace are reflected in the depot.

The commands p4 add, p4 edit, and p4 delete do not immediately add, edit, or delete files in the depot. Instead, the affected file and the corresponding operation are listed in the default changelist, and changes to the files in the depot occur only after the changelist is submitted to the depot with p4 submit.

Changelists enable you to send updated sets of files to the depot in indivisible, or atomic, transactions: when a changelist is submitted, either all of the files in the changelist are committed, or none of the files are committed.


This chapter discusses only the default changelist, which is automatically maintained by Perforce.

Changelists are a key concept in Perforce. For a full discussion, see Chapter 7, Changelists.

When a file has been opened with p4 add, p4 edit, or p4 delete, but the corresponding changelist has not yet been submitted in the depot, the file is said to be open (for add, for edit, or for delete) in the client workspace.

Adding files to the depot

To add a file (or files) to the depot, type p4 add filename(s). The p4 add command opens the file(s) for add and includes the files in the default changelist.

After you have added files to the changelist, you must submit your changelist to the depot by using the p4 submit command. See "Submitting your changes to the depot" on page 32 for details.

In the example shown, the filenames are displayed as filename#1. The #n suffix is used by Perforce to indicate the nth revision of this file. The first revision of any file is revision #1. Revision numbers are always assigned sequentially.

Adding more than one group of files at once

You can supply multiple file arguments on the command line. For example:

Populating an empty depot

In Perforce, there is no difference between adding files to an empty depot and adding files to a depot that already contains other files. You can populate a new, empty depot by adding files from a client workspace with p4 add as described above.

Editing files in the depot

To open a file for edit, use the p4 edit command to open the file for edit in the default changelist. Opening a file for edit has three effects:

After you have opened a file for edit and made the required changes in your client workspace, use the p4 submit command make your changes available to other users by submitting the changelist. See "Submitting your changes to the depot" on page 32.


Before you can open a file for edit, someone must have already added the file to the depot with p4 add, or copied into your client workspace from the depot with p4 sync.

Deleting files from the depot

To delete a file from the depot, use the p4 delete command to open the file for delete in the default changelist.

The p4 delete command deletes the file from your client workspace as soon as you run the p4 delete command, but deletion of the file in the depot does not occur until you use p4 submit to submit the changelist containing the delete operation to the depot.

After you submit a changelist with a file deletion, it appears to all users as though the file is deleted from the depot. Actually, only the most recent revision (or head revision) of the file is marked as deleted. Older revisions of the file are not removed, and by specifying these older revisions, you can always recover old revisions of "deleted" files back into your client workspace.

Submitting your changes to the depot

In Perforce, changelists are used to group related changes (for example, a bug fix, or the addition of a new feature to a product) in a logical fashion. Most changelists contain more than one file. None of the operations you perform on files (such as opening for add, edit, or delete) take effect in the depot until you commit your changes to the depot by submitting the changelist.

Submitting a changelist to the depot works atomically: either all the files in the changelist are updated in the depot, or none of them are. (In Perforce terminology, this is called an atomic change transaction).

To submit a changelist, use the p4 submit command.

The p4 submit form includes a Description: field; you must supply a description in order for your changelist to be accepted.

The Files: field contains the list of files in the changelist. If you remove files from this field, any files not included in the changelist are carried over to a new default changelist, and reappear the next time you use p4 submit.

If a directory containing a new file does not exist in the depot, the directory is automatically created in the depot when you submit the changelist.

When you run p4 submit, the operating system's write permission on the submitted files in your client workspace is turned off. Write permissions are restored when you open a file for editing with p4 edit.


If a submit fails due to a file conflict, the default changelist is assigned a number, and you'll need to submit that changelist in a slightly different way.

See Chapter 5, Perforce Basics: Resolving File Conflicts for details on submitting numbered changelists.

Backing out: reverting files to their unopened states

To back out unwanted changes made for files that you opened for add, edit, or delete, use the p4 revert command. This command restores the file in the client workspace to its unopened state, and any local modifications to the file are lost.

If you use p4 revert on a file you opened with p4 delete, the file reappears in your client workspace immediately. If you revert a file opened with p4 add, the file is removed from the changelist, but is left intact in your client workspace.

If you revert a file you originally opened with p4 edit, the last synced version is written back to the client workspace, overwriting the edited version of the file. To reduce the risk of accidentally overwriting your changes, you can preview any revert by using p4 revert -n before running p4 revert. The -n option reports what files would be reverted by p4 revert without actually reverting the files.

Basic reporting commands

Perforce provides many reporting commands. Each chapter in this manual ends with a description of the reporting commands relevant to the chapter topic. All the reporting commands are discussed in greater detail in Chapter 11, Reporting and Data Mining.

The most basic reporting commands are p4 help and p4 info.


p4 help commands

Lists all Perforce commands with a brief description of each.

p4 help command

For any command provided, gives detailed help about that command. For example, p4 help sync provides detailed information about the p4 sync command.

p4 help usage

Describes command-line flags common to all Perforce commands.

p4 help views

Gives a discussion of Perforce view syntax.

p4 help

Describes all the arguments that can be given to p4 help.

p4 info

Reports information about the current Perforce system: the server address, client root directory, client name, user name, Perforce version, and licensing information.

Two other reporting commands are useful when getting started with Perforce:


p4 have

Lists all file revisions synced to your client workspace.

p4 sync -n

Report the set of files that would be updated in the client workspace by a p4 sync command without actually performing the sync operation.

Perforce 2005.1 User's Guide
<< Previous Chapter
Connecting to the
Perforce Server

Table of Contents
Perforce on the Web
Next Chapter >>
Perforce Basics:
The Details

Please send comments and questions about this manual to [email protected].
Copyright 1997-2005 Perforce Software. All rights reserved.
Last updated: 05/12/05