The Perforce Public Depot Tutorial


NOTE These instructions are for registered Public Depot contributors only. See the Public Depot home page for more information.

Setting Up Your Workspace

Back to
Table of

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 to One of these commands will probably work for you:

    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.

  2. Pick a client workspace name. We recommend you use your Public Depot username for your workspace name as well. For example, if your username is cary_grant, your client workspace name should also be cary_grant.

  3. Set P4CLIENT to your workspace name using the one of these commands:

    setenv P4CLIENT cary_grant   
    On Unix (csh) -- this also goes in your .cshrc
    export P4CLIENT=cary_grant   
    On Unix (ksh) -- this also goes in your .login

    p4 set P4CLIENT=cary_grant   
    In MS-DOS on Windows

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

    p4 client 
    In the editor, you'll see something like the form shown below. 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:

    Client: cary_grant
    	Created by cary_grant.
    Root:   C:\
    Options:	nomodtime noclobber
    	//public/...    //cary_grant/...
    	//guest/...     //cary_grant/... 

  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: cary_grant
    	Cary Grant's workspace.
    Root:   C:\ws
    Options:	nomodtime noclobber locked
    	//guest/cary_grant/...    //cary_grant/...

Creating Your Guest Branch

Back to
Table of

When you register as a Public Depot contributor, you are given write access to your guest branch, but your guest branch is not actually created for you. (Because we don't know which projects you want to work on.) So you must create your own guest branch. It will start out as a clone of one of the projects in the //public path, and you will submit additions or changes to it.

For example, if Cary Grant wanted to contribute a script to the Perforce utilities project, he'd start out by branching the //public/perforce/utils project into his //guest/cary_grant branch. Here's how he'd do it:

First, open the files for branching:

p4 integ -v //public/perforce/utils/... //guest/cary_grant/perforce/utils/... 
The "-v" flag speeds up the operation by opening "virtual" files -- that is, these files are opened, but not yet present in your workspace.

Next, submit the opened files:

p4 submit

Note that these two commands haven't moved any files in or out of Cary Grant's workspace. All they've done is created a set of files in the Public Depot's //guest/cary_grant/perforce/utils path that exactly mirror the files in //public/perforce/utils.

Filling Your Workspace

Back to
Table of

Once you have set up your workspace and created your guest branch, you can fill your workspace with files from the depot using:

p4 sync

This copies depot files to your workspace. For example, when Gary Grant runs p4 sync, files from the //guest/gary_grant branch are copied into his local c:\ws directory. When it's done, his workspace is "in sync" with the depot.


Working on Files

Back to
Table of

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, here Cary Grant opens two P4DB source files for editing:

cd c:\ws\perforce\utils\p4db

p4 edit index.cgi chb.cgi

Now these files are "opened for edit". Once opened for edit, files become writeable, 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.

For example, Cary Grant is adding a new file to the P4DB suite. First he creates the file with vi, then adds it:

cd c:\ws\perforce\utils\p4db
vi jbv.cgi 

p4 add jbv.cgi

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

Deleting files

To delete files:

p4 delete fdv.cgi fv.cgi flv.cgi

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 undo changes you've made to any of your opened files, use p4 revert. For example:

p4 revert fdv.cgi flv.cgi

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!


Submitting A Changelist

Back to
Table of

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 form, where you must replace the string "<enter description here>" with a valid description of the changes you are submitting. Cary Grant's changelist form looks like:

Change: new

Client: cary_grant

User:   cary_grant

Status: new

    Added job searching to the P4DB browser.	

    //guest/cary_grant/perforce/utils/p4db/index.cgi  # edit
    //guest/cary_grant/perforce/utils/p4db/chb.cgi    # edit
    //guest/cary_grant/perforce/utils/p4db/jbv.cgi    # add
    //guest/cary_grant/perforce/utils/p4db/fv.cgi     # delete

When you are done typing the description, save the file and exit the editor -- your changelist will be submitted and the depot files updated.

Pulling Changes into Your Branch

Back to
Table of

The files in your guest branch are insulated from the files in the //public path they were branched from. From time to time, files in //public will be added as Public Depot project curators integrate changes from guest branches. If the project you made your branch from gets updated, you will need to pull those updates into your own guest branch.

So Cary Grant, for example, has been working on his P4DB enhancement. As you recall, his guest branch files were originally branched from the //public/perforce/utils path. To find out if any changes need to be pulled from that path into his own guest branch, Cary uses:

If he sees files listed, he knows he'll have to pull changes into his guest branch. Here's how he does it:

  1. He submits (or reverts) any opened files in his workspace.

  2. He opens files for integration in his workspace using:

    p4 integ //public/perforce/utils/... //guest/cary_grant/perforce/utils/... 
    (This is the same as the command above, without the -n. It's also exactly the same as the command that created his branch, without the -v.)

  3. He resolves the opened files using:

    p4 resolve 

  4. He submits the opened, resolved files with:

    p4 submit 

At this point, Cary Grant's guest branch is fully integrated. That is, all changes in //public/perforce/utils have been pulled into //guest/cary_grant/perforce/utils.

Resolving Files

Back to
Table of

Resolving is how you merge specific changes from one file to another. For each file, you'll see stats like:

    c:\ws\perforce\utils\p4db\index.cgi - merging //public/perforce/utils/p4db/index.cgi#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.


Copyright 1998
Perforce Software
You're browsing a file stored as
$Id: //public/tutorial.html#1 $
in the Perforce Public Depot.
Back to
Table of