Perforce Quick Start for New Users

This guide is for p4 users.

The Basic Steps

Other Stuff You'll Need to Know About

Setting Up A Workspace

Filling A Workspace

Working on Files

Submitting A Changelist

Updating a Workspace

Resolving Files

Submit Errors

Re-submitting a Changelist

Documentation

Client Workspace Names

Depot Project List

Changelist descriptions

Definitions

Windows 95/NT Documentation


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.

  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.

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

[TOP]

Filling A Workspace

Once you have set up your workspace you can fill it with files from the depot using:

p4 sync

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

Note:

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:

[TOP]

Working on Files

Once you have filled your workspace, you can work on files. You can edit files, add files, delete files, and revert files to their original state.

Note:

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:

[TOP]

Submitting A Changelist

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.

[TOP]

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
...and a prompt like:
	Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [at]:
Follow the prompt's advised action by hitting return. The prompt shows [in square brackets] which action it advises you to take.

Note:

[TOP]

Submit errors

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'
What this means is that your changelist has been assigned a number -- 5047, in this example -- but it has not been submitted. You'll have to resolve your files before you can re-submit your changelist.

[TOP]

Re-submitting a changelist

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:

[TOP]

Client workspace names

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

	yourlogin-yourmachine

E.g., if your login is "socks" and your machine is called "whitehouse", you would use "socks-whitehouse" as your client name.

Note:

[TOP]

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:

Project path Project description Who has access Who can submit changes
//depot/proj/jam/...
Jam/MR project development. Everyone Jam development team
//depot/main/jam/...
Jam/MR mainline code. Everyone Maintenence engineering & Jam team
//depot/r2.0/jam/...
Jam/MR Release 2.0 Everyone QA only
//depot/dev/omni/...
New omni product development Omni group members only Omni group

[TOP]

Changelist descriptions

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

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.

[TOP]

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

[TOP]

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:

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.

[TOP]

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