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:

setenv P4PORT mars:1666   

export P4PORT=mars:1666   

p4 set P4PORT=mars:1666   

Setting P4CLIENT

setenv P4CLIENT bruno-dev

export P4CLIENT=bruno-dev

p4 set P4CLIENT=bruno-dev

Configuring the client root

1. Issue the following command:

p4 client

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

Client: bruno-dev

Description: 
	 Created by bruno. 

Root:   C:\

View:
	 //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:

• Edit files: check out files, open them using your preferred editor, make changes and save them. If you want to discard your changes, you can revert the edited files, restoring the version you synced.
• Add files: create new files and mark them for addition to the Perforce server.
• Delete files: mark files for deletion from the Perforce server.

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

Editing files

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

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.

Change: new

Client: bruno-dev

User:   bruno

Status: new

Description: 
	<enter description here>	


Files:
	//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

Copyright © 2006 Perforce Software