Perforce QuickStart for New P4 Users

The goal of this quickstart page is to enable a new Perforce command-line user to get up and running as fast as possible. This quickstart is written with the assumption that you already have a Perforce server up and running. If you don't, you can set one up for demonstration purposes.

The following sections tell you how to perform four basic tasks:

  1. Setting up a workspace: creating an area on your machine where you can work with copies of files stored in your Perforce server.
  2. Populating a workspace: retrieving files from your Perforce server.
  3. Working on files: checking files out of the server and editing them.
  4. Submitting your changes: checking files into the server.

Setting Up A Workspace

The first thing you do when you use Perforce is to set up a personal client workspace on your local machine. This setup is only done once.

To create a workspace:

  1. Set P4PORT
  2. Set P4CLIENT
  3. Configure the client root

Setting P4PORT

The P4PORT environment variable specifies the host and port of your Perforce server. Your Perforce administrator can tell you what P4PORT setting to use. For example:

Unix (csh)
setenv P4PORT mars:1666   
Put this in your .cshrc or you'll have do this for every session.  
UNIX (ksh)
export P4PORT=mars:1666   
Put this in your .profile or you'll have do this for every session.
p4 set P4PORT=mars:1666   
Issue this command in a DOS window

Setting P4CLIENT

The P4CLIENT environment variable specifies your client workspace name. Pick a client workspace name or ask your Perforce administrator to assign you one. For example:

UNIX (csh)
setenv P4CLIENT bruno-dev
Put this in your .cshrc or you'll have do this for every session.  
UNIX (ksh)
export P4CLIENT=bruno-dev
Put this in your Profile or you'll have do this for every session.
p4 set P4CLIENT=bruno-dev
Issue this command in a DOS window

Configuring the client root

The client root specifies the location of your client workspace on your local machine. By default, it's the root directory of your machine, so be sure to set it to a higher-level directory, as follows:

1. Issue the following command:

p4 client

Perforce launches a text editor, displaying a client workspace specification form. For example:

Client: bruno-dev

	 Created by bruno. 

Root:   C:\

	 //depot/...    //bruno-dev/...

2. Edit the Root field, shown in red.

Specify the root of the directory you want to use as a workspace on your local filesystem. You do not need to create the directory: Perforce creates directories as required.

3. Save and exit the editor.

Populating A Workspace

After you have set up your workspace, you can retrieve files from the Perforce server. Assuming you are working with a test server containing a small number of test files, you can retrieve all the files by typing:

p4 sync

If you want to retrieve a subset of the files in the depot, specify the files that you want to sync. For example, to retrieve only the files in and under the "project1" directory, issue the following command:

p4 sync //depot/project1/...

For details about the p4 sync command, refer to the Perforce Command Reference.

Working on Files

Now you can modify the files in your workspace. You can:

None of the changes you make in your workspace affect files in the Perforce server until you submit them.

Editing files

To check out files, issue the p4 edit command. For example, to check out Jambase, jam.h, and jam.c, issue the following command:

p4 edit Jambase jam.h jam.c

Now these files are opened for edit. Perforce sets permissions so they are writable. Open them with your preferred editor, make your changes and save them.

If you decide you want to discard your changes and restore a file in your workspace to the version you synced, issue the p4 revert command. For example:

p4 revert Jambase jam.h jam.c

Adding new files

To add files to the Perforce server, create the files in a directory under your workspace root, then issue the p4 add command. For example, assuming you've created files called dyncreate.c and dyn.h, issue the following command:

p4 add dyncreate.c dyn.h 

Now the new files are opened for add. If you decide you don't want to add the files after all, issue the p4 revert command.

Deleting files

To delete files from both the Perforce server and your workspace, issue the p4 delete command. For example:

p4 delete demo.txt readme.txt
The specified files are removed from your workspace and marked for deletion from the server. If you decide you don't want to delete the files after all, issue the p4 revert command. When you revert files opened for delete, Perforce restores them to your workspace.

Submitting Your Changes

As you edit, add, and delete files, Perforce creates and maintains a list of the files you are changing and the associated actions. This list is called a changelist. To check in your changes, you submit your changelist by issuing the p4 submit command.

When you issue the p4 submit command, Perforce launches a text editor containing the changelist. For example:

Change: new

Client: bruno-dev

User:   bruno

Status: new

	<enter description here>	

	//depot/dev/omni/svr/dyncat.c            # edit
	//depot/dev/omni/svr/dynch.c             # edit
	//depot/dev/omni/include/dyn.h           # edit
	//depot/dev/omni/svr/dyncreate.c         # add
	//depot/dev/omni/svr/ransort.c           # delete
	//depot/dev/omni/svr/random.c            # delete

Edit the description, then save and exit the editor. Perforce submits your changelist and the associated files to the server.

Note: Sometimes while you have a file open for edit, someone else submits changes to the same file. In this case, Perforce displays an error when you try to submit your changelist. Here's an example of what a submit error looks like:

   Submitting change 5047.
   //depot/dev/omni/svr/dynch.c - must resolve before submitting
   //bruno-dev/dev/omni/svr/dynch.c - must resolve //depot/dev/omni/svr/dynch.c#7    
   Out of date files must be resolve or reverted.
   Merges still pending -- use 'resolve' to merge files.
   Submit failed -- fix problems above them use 'submit -c 5047'

You'll have to resolve your files before you can resubmit your changelist. For details about resolving, refer to the P4 User's Guide.

More Information

If this is your first experience with Perforce, read Introducing Perforce. For detailed information about a command, issue the p4 help command or refer to the Perforce Command Reference. For details about using the command line, refer to the P4 User's Guide. All documentation is available from the Perforce technical documentation web page.

Copyright © 2006 Perforce Software