Perforce Quick Start for New 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  


Client Workspace Names 

Depot Project List 

Changelist descriptions 


Windows 95/NT Documentation 

Setting Up A Workspace

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

    setenv P4PORT   
    On Unix (csh). Put this in your .cshrc or you'll have do this for every session. 
    On Unix (ksh). Put this in your .login or you'll have do this for every session. 


    p4 set   
    In MS-DOS on Windows. 
  3. Pick a client workspace name, following our naming convention.
  4. Set P4CLIENT to your client name. E.g.,
  5. setenv P4CLIENT ctaguest   
    On Unix (csh) -- this also goes in your .cshrc 
    export P4CLIENT=ctaguest   
    On Unix (ksh) -- this also goes in your .login 


    p4 set P4CLIENT=ctaguest           
    In MS-DOS on Windows 
  6. Bring up the client specification form editor, using:


    p4 client 
    In the editor, you'll see something like this:
    Client: ctaguest
            Created by socks.
    Root:   C:\
            //depot/...    //ctaguest/... 
    The text shown in red is what you must edit to set up your client workspace. The text in green may be edited if you wish.
  8. When you have modified your client spec, save it and exit the editor. Here's an example of a completed client workspace specification:
  9. Client: ctaguest
            Socks' workspace for Jam project.
    Root:   C:\ws
            //depot/proj/jam/...    //ctaguest/jam/...

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.


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.



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.


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!



Warning all the following commands are unavailable to the ctaguest user, however they are available to developers.

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: otdeveloper1

User:   socks

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


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.



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.

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

Client workspace names

Your client workspace name should follow the form:
E.g., if your login is "socks" and your machine is called "whitehouse", you would use "socks-whitehouse" as your client name.



Depot project list

Select one or more of these project paths for your view mapping lines:
Project path  Suggested mapping  Description  Who can sync  Who can submit 
Drivers/Alls OSs  Anyone  Developers 
API Development  Anyone  Developers 

Changelist descriptions

When you fill out the changelist description form, please follow these guidelines: Here's an example of a completed changelist 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.


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, use:


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.

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


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 Index 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 Perforce Software
Last updated: Sept. 21, 1998