The Perforce Public Depot Tutorial

About This Tutorial

The instructions in this tutorial are for registered Public Depot contributors only. See the Public Depot home page for more information.

Because the bulk of the Public Depot is populated by Perforce-related content, we expect the typical contributor to be an experienced Perforce user. However, Jam/MR contributors may not necessarily be familiar with Perforce, so this tutorial was written to be useful to new Perforce users as well as experienced users.

The tutorial examples use p4, Perforce's command line interface. You can click on the book icon next to each command to go to the command reference section that describes it.

Complete documentation for all Perforce commands and programs is available on our technical documentation page.

If you're using P4Win, our Windows GUI, you'll want to have a copy of our p4 to P4Win Translation Guide handy so you can look up the GUI equivalents of the commands shown here. The Translation Guide can be downloaded from our technical documentation page.

Setting Up Your Environment

Before you can use Perforce with the Public Depot you'll need to set these environment variables:

P4PORT	To use the Public Depot, set this to public.perforce.com:1666
P4USER	Set this to your registered Public Depot user name. For example, Cary Grant's registered user name is cary_grant.
P4PASSWD	Set this to your Public Depot password.
P4CLIENT	Set this to your client workspace name. You can use your Public Depot uuser namefor your workspace name as well. E.g., Cary Grant could name his client workspace cary_grant.

There are many ways to set environment variables. Two of those ways are shown here, as examples:

1. Unix users running csh can use setenv:
% setenv P4PORT public.perforce.com:1666
% setenv P4USER cary_grant
% setenv P4PASSWD thornhill
% setenv P4CLIENT cary_grant
2. Windows users can use p4 set to set Perforce environment variables in the Windows registry:
C:\> p4 set P4PORT=public.perforce.com:1666
C:\> p4 set P4USER=cary_grant
C:\> p4 set P4PASSWD=thornhill
C:\> p4 set P4CLIENT=cary_grant

Creating Your Client Workspace

The first thing you do when you use Perforce is set up a client workspace on your local machine. This setup is only done once. 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

Description: 
	Created by cary_grant.

Root:   C:\

Options:	nomodtime noclobber

View:
	//public/...    //cary_grant/...
	//guest/...     //cary_grant/...

• 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.) For the sake of this tutorial, we'll Cary Grant's workspace root is c:\ws.
• In the Options field, add the word locked to prevent other users from modifying your workspace specification.
• The View field is a list of "view mapping" lines. The left side of each line is a depot directory path, and the right side shows how that path will be mapped into your workspace. The client name on the right side of each mapping stands for the workspace root. For working in the Public Depot you most likely need only map to your guest branch as shown below. (If you are sharing development with another Public Depot contributor, and wish to work in his or her guest branch, see "Sharing Development".)

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

Description: 
	Cary Grant's workspace.

Root:   C:\ws

Options:	nomodtime noclobber locked

View:
	//guest/cary_grant/...    //cary_grant/...

Creating Your Guest Branch

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 enhancements to some of the Perforce utilities, 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 will not be copied to and from 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

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.

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.

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:

• 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, 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 wwritable 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!

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.

Submitting files

When you are satisfied with the changes in your workspace, you can submit them to the depot with:

p4 submit

Pulling Changes into Your Branch

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:

p4 integ -n //public/perforce/utils/... //guest/cary_grant/perforce/utils/...

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.

Submitting A Changelist

As you open files with p4 edit, p4 add, and p4 delete, you are building up a changelist. A changelist is also created when you open files with p4 integ. However, until you submit your changelist, files in the depot are unaffected by your intended changes. "Submitting" sends modified file content from your workspace to the depot, and updates depot versions of the files.

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

Description: 
    Added job searching to the P4DB browser.	

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

Note that all files in all guest branches are readable to everyone, so as soon as you submit your changelist, other contributors can see and review your changes.

Resolving Files

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.

Note:

• For each file resolved, Perforce does a 3-way merge between files it refers to as "yours", "theirs", and "the base". The merged result is written to your workspace file.
  • If you are integrating new changes from one branch to another, "yours" is the target file in your workspace, "theirs" is the newer file in the originating branch, and "the base" is the version of the file in the originating branch that was last integrated from.
  • If you are syncing opened workspace files with newer depot files, "yours" is the target file in your workspace, "theirs" is the newer file in the depot, and "the base" is the version of the file you had when you opened it for edit.
• 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.

Publishing Your Changes

As a contributor, you may only submit changes to your own branch in the //guest depot. To have your changes "published", you must ask a project curator to integrate them from your branch to the //public depot.

To request publication:

• Make sure your guest branch is fully up to date with the project it was integrated from. (See Pulling Changes into Your Branch.)
• Send email to the project curator asking to have your changes published. The curator's name and email address can be found in the index.html page for the project.

Sharing Development

If you and other registered Public Depot contributors would like to share development on a project, you can designate one of your guest branches as a shared branch. The owner of the shared branch should email requesting that his or her branch be opened for shared development, and naming the other contributors who should be granted write access to that branch.

For contributors working in a shared branch, all of the above instructions apply, with these caveats:

• Each contributor should use p4 client to set his or her client view to the shared guest branch instead of to his/her own guest branch.
• Although you are all working in the same shared guest branch, each of you still has your own client workspace. Your changes aren't actually shared until you submit your changelist into the depot.
• When someone else submits a changelist, you'll need to re-sync your workspace (as described in Filling Your Workspace) and, if necessary, resolve opened files.
• If you try to submit a changelist without having re-synced and resolved, your submit will fail. This isn't a problem, it just does this to give you a chance to resolve files first. The failed submit assigns a number to the pending changelist. After you resolve your opened files, you must give the changelist's number on the submit command, e.g:

  p4 submit -c 1453

Being A Project Curator

If you are a curator of a project in the Public Depot (and you know who you are) your first responsibility is to maintain an index.html file at the top level of the project subdirectory in the //public path. This document should at least describe the purpose of the project, and list your name and email address. (Or, for spam-proofing, your decodable email address.)

Your second responsibility is to "publish" contributions to the project by integrating changes from guest branches into the //public project path. You'll receive email requests to publish contributions. When you receive a request:

1. Make sure the contributor's guest branch is up to date with the public project path.
2. Review the changes in question for functionality and appropriateness for your project.
3. Integrate the changes from the guest branch into the public project path.

For example, say you are the curator of the //public/perforce/utils project and you get email from Cary Grant requesting that you publish his enhancements to the P4DB browser. Here are some tips for reviewing and integrating his contribution:

• Note that to integrate any contributor's changes into //public/perforce/utils, you'll need to have that path mapped in your client workspace view.
• Never integrate more than one contribution at a time. (E.g., don't combine Cary Grant's P4DB contribution with James Mason's FAQ contribution.)
• Start by taking a look at Cary's changelist descriptions. You can list them with:

  p4 changes //guest/cary_grant/...

• To make sure Cary has integrated all published changes into his guest path, add //guest/cary_grant/... to your client view and try this:

  p4 flush //guest/cary_grant/perforce/utils/...

  p4 integ -n //public/perforce/utils/... //guest/cary_grant/perforce/utils/...

  If this shows unintegrated files, send Cary mail telling him he needs to pull the latest //public/perforce/utils changes into his guest branch before you can publish his contribution. (p4 flush simulates a sync without copying files to your workspace.)

• Before opening the //public/perforce/utils files for integration, remember to sync first:

  p4 sync //public/perforce/utils/...

  p4 integ //guest/cary_grant/perforce/utils/... //public/perforce/utils/...

• Do a "safe" resolve, and make sure all merges could be done without conflicts:

  p4 resolve -as //public/perforce/utils/...

  p4 resolve -n //public/perforce/utils/...

  The second resolve should show that everything is already resolved. If this is not the case, either Cary did something wrong pulling in the latest changes into his branch, or you aren't synced to the latest //public/perforce/utils files.

• Diff the opened files in your workspace after they've been resolved and before you submit them. You can use:

  p4 diff

  to see exactly what you'd be changing if you submitted this contribution.

You're browsing a file stored as $Id: //public/tutorial.html#17 $