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.

1. Set P4PORT to point to your Perforce server. Your Perforce administrator can tell you what P4PORT setting to use. For example:

   	setenv P4PORT mars:1666	On Unix (csh). Put this in your .cshrc or you'll have do this for every session.
   	export P4PORT=mars:1666	On Unix (ksh). Put this in your .profile or you'll have do this for every session.
   	p4 set P4PORT=mars:1666	In MS-DOS on Windows.

   If you don't have a Perforce server installed at your site, you can set one up for demo purposes. Go to the Perforce home page and follow the links to the "Ten Minute Demo".

2. Pick a client workspace name. Your Perforce administrator may have a naming convention you should use.

3. Set P4CLIENT to your client workspace name. E.g.,

   	setenv P4CLIENT socks-whitehouse	On Unix (csh) -- this also goes in your .cshrc
   	export P4CLIENT=socks-whitehouse	On Unix (ksh) -- this also goes in your .profile
   	p4 set P4CLIENT=socks-whitehouse	In MS-DOS on Windows

4. Bring up the client specification form editor, using:

   p4 client

   In the editor, you'll see something like this:

   Client: socks-whitehouse Description: Created by socks. Root: C:\ View: //depot/... //socks-whitehouse/...

   Edit the text shown in red to set up your client workspace.

   • You can change the Description field if you like -- it's just a comment.

   • In the Root field, put the root of the directory you will be using as a workspace on your local filesystem. (The directory doesn't have to exist yet; Perforce will create it for you.)

   • The View field is a list of "view mapping" lines. The left side of each line is a depot directory path. The right side is where that directory will be mapped into your workspace. The client name on the right side of each mapping stands for the workspace root.

     Your Perforce administrator may have set up a depot project list you can choose your mappings from. You may have as many view mapping lines as you wish, but you should not map to more directories than you need to work with.

     If you are experimenting with your own Perforce demo server, you can leave the default mapping unchanged.

5. When you have modified your client spec, save it and exit the editor. Here's an example of a completed client workspace specification:

   Client: socks-whitehouse Description: Socks' workspace for Jam project. Root: C:\ws View: //depot/proj/jam/... //socks-whitehouse/jam/... //depot/dev/omni/... //socks-whitehouse/omni/...

p4 sync

This copies depot files to your workspace. When it's done, your workspace is "in sync" with the depot.

Note:

• Synced files have read-only permission in your workspace (until you start working on them).

• Perforce will sync to the head revisions of depot files, by default.

• If you run p4 sync more than once, nothing will happen the second time unless there are newer versions in the depot that are not yet in your workspace.

• If you are running p4 sync and you get disconnected, you can run it again to continue filling your workspace. Files that have already been copied to your workspace will not be copied a second time.

Updating a workspace

Updating a workspace is exactly the same as filling it. You should use p4 sync regularly to update your workspace with the latest revisions of files.

Note:

• Only the depot files that have changed will be copied to your workspace.

• Opened files will be untouched by p4 sync. After you sync, you have to resolve opened files to merge in changes from the depot.

Note:

• None of the commands described here affect the files in the depot. All they do is allow you to work on files. Perforce tracks the files you're working on in a changelist. As you open files, they go on your changelist. You have to submit your changelist to get your changes into the depot.

Editing files

To edit files, use the p4 edit command on them. For example:

p4 edit Jambase jam.h jam.c

Now these files are "opened for edit". They are now writeable by you, so you can edit them or modify them by any other means.

Adding new files

To add new files, create them first, with an editor or other tool. You must create them in a directory under your workspace root. Then use the p4 add command on them, e.g.:

p4 add dyncreate.c dyn.h

p4 add "opens files for add", which tells Perforce you plan to add them to the depot.

Deleting files

To delete files:

p4 delete demo.txt readme.txt

This removes the files from your workspace, and makes them "open for delete", which tells Perforce you plan to delete them from the depot. p4 delete only works on files put in your workspace by p4 sync.

Reverting files

If you ever want to get rid of the changes you've made to any of your opened files, use p4 revert. For example:

p4 revert jam.c

This restores files to their original states and takes them off your changelist.

Warning: p4 revert is IRREVERSIBLE! When you revert a file that was opened for edit, Perforce replaces the file in your workspace with a fresh, read-only version directly from the depot. Any edits you've made to the file will be lost!

Note:

• When you revert files opened for delete, Perforce restores them to your workspace.

• When you revert files opened for add, Perforce doesn't do anything to the files; it simply takes them off your changelist. The new files you created in your workspace will still be there.

As you open files with p4 edit, p4 add, and p4 delete, you are building up a changelist. When you are satisfied with your changelist, you can submit it into the depot. "Submitting" copies opened files from your workspace to the depot -- until then, files in the depot are unaffected by your work.

To submit your changelist, use:

p4 submit

This puts you in an editor, where you'll see something like this:

Change: new

Client: socks-whitehouse

User:   socks

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

The text you see in red must be replaced with a valid changelist description. When you are done typing the description, save the file and exit the editor -- your changelist will be submitted and the depot files updated.

Note: If any of the files you submit have been changed by someone else first, you'll get a submit error. When this happens, you must resolve your files and then re-submit your changelist.

That's it for the basic steps. The following sections are really just sidebars and footnotes. ("Other stuff you'll need to know about.")

Resolving Files

Resolving files is how you merge in someone else's changes with your changes, when you've both been working on the same files.

For example, say you synced the file main.c to your workspace when it was at revision #6 in the depot. Then you opened it for edit. Then someone else submitted revision #7 into the depot. Resolving allows you to merge the changes from the depot's main.c#7 into your workspace's opened copy of the file.

Note that files in your workspace don't actually need resolving until you either update your workspace, or get a submit error trying to submit files that have been changed in the depot by someone else.

To see which of your opened files need resolving, use:

p4 resolve -n

Resolving takes place in your workspace. For each file, Perforce does a 3-way merge between the modified file in your workspace, the modified file in the depot, and the file you were originally synced to. These are files are called "yours", "theirs", and "the base", respectively. The merged result is written to your workspace file.

To enter the resolve program, use:

p4 resolve

For each file, you'll see stats like:

	c:\ws\jam\main.c - merging //depot/proj/jam/main.c#7
	Diff chunks: 0 yours + 2 theirs + 0 both + 0 conflicting

	Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [at]:

Note:

• If there are no conflicting diffs, the merged result will be saved in your workspace file, and the resolve program will go on to the next file.

• If there are conflicting diffs, you will be put into an editor to resolve the conflicts. The conflicts will be marked by lines beginning with >>>>, ====, or <<<<. For example:

       >>>> ORIGINAL
       i = i + j
       ==== THEIRS
       if ( i < n ) then i = i + j
       ==== YOURS
       if ( i <= n ) then i = i + j
       <<<< 
      

  While in the editor, your job is to look for the conflicts, remove the conflict markers (shown here in red), and modify the remaining text in a way that makes sense. When you exit the editor, the prompt will advise you to accept the merged result.

• You can diff files while you're in the resolve program. At the prompt, type ? and you will be shown the diff commands.

• You can choose to skip any file and re-run resolve on it later. Your workspace file will be untouched if you do this.

Sometimes when you've been working on files, other people will have submitted changes to the same files. If you haven't updated your workspace periodically and resolved files, you'll get a submit 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
	//socks-whitehouse/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'

A submit error will cause your changelist to be numbered. Numbered changelists must be submitted using the assigned number on the p4 submit command. For example:

p4 submit -c 5047

Note:

• The description you typed in before will be used automatically and the changelist immediately submitted.

• If you want to check or edit the changelist description before resubmitting, use the p4 change command, giving the assigned number, e.g.:

  p4 change -c 5047

• If you don't remember the changelist number, you can display it with:

  p4 opened

Client workspace names

Most large Perforce sites have client workspace naming conventions. We suggest your client workspace names follow the form:

	yourlogin-yourmachine

Note:

• Don't use "@" or "#" characters in your client workspace name. (These have special meanings to Perforce.)

• Don't use a client workspace name that someone else has already taken. You can list existing client names with:

  p4 clients

Depot project list

If the Perforce installation at your site is huge, you'll want to limit your client workspace view to a subset of the entire depot. Your Perforce administrator can give you a depot project list and suggest mappings for you to use. Here's a sample depot project list:

//depot/proj/jam/...

//depot/main/jam/...

//depot/r2.0/jam/...

//depot/dev/omni/...

Changelist descriptions

Some Perforce sites have specific guidelines you should follow when filling out a changelist description. Here are some general-purpose guidelines:

• The first line of the description should summarize the change. You can put as much detail as you want on the following lines.

• You don't need to say which files you've changed -- that information is already stored with the changelist.

• If you are using a text editor to enter the description, be sure to leave a margin on the left.

Here's an example of a completed changelist description:

Description: 
	Tech note cleanup.
	Removed TN 24 & TN 29 entirely; those topics are now
	covered in the Users Guide. Updated TN 12 to include 
	new filetypes. Updated index: added a preface; moved 
	TN 7, 8, and 14 to the "Previous releases" section.

Definitions

Depot

The master repository of all files managed by Perforce. You can't work directly on depot files; Perforce makes local copies of them for you. P4PORT holds the address of the Perforce server that manages the depot. To confirm you can connect to the Perforce server, run:

p4 info

Client workspace

The local directory structure that holds the files you're working on. Perforce keeps track of which files are being worked on in each client workspace. Every client workspace has a unique name. You tell Perforce the name of the client workspace you want to use by setting P4CLIENT. To confirm which workspace you're using, run p4 info as shown above.

Changelist

A set of changed files which can be -- or has been -- submitted to the depot. Perforce tracks pending changelists and maintains a permanent record of all submitted changelists.

Opened files

Files that Perforce knows you are working on. To see which files are opened in your workspace, use:

p4 opened

Opened files are always in a pending changelist (although they may not all be in the same changelist).

Documentation

This quick start guide briefly describes the common day-to-day Perforce tasks. The Perforce Technical Documentation page provides links to all Perforce documentation, including:

• The p4 User's Guide, which provides an in-depth description of all of Perforce's features, and contains a complete glossary of terms.

• The p4 Command Reference, which gives detailed descriptions of each p4 command.

You can also get command help from:

p4 help

Also, you can click on any "open book" icon in this guide to go directly to the p4 Command Reference entry for the command next to it.

Documentation for Windows 95/NT Users

If you're using P4Win, the Perforce Windows GUI, you can use its Help feature to find out how to do the basic operations. You may also look up any p4 command in the Perforce p4 to P4Win Translation Guide to see exactly how you'd do the equivalent operation in P4Win. The Translation Guide can be downloaded from the Perforce Technical Documentation page.

Copyright 1998, 2000 Perforce Software
Last updated: Sep. 5, 2000