This page is for users new to Perforce and P4Web. It describes how to use a P4Web Helper to do the common Perforce tasks: setting up a workspace, filling a workspace ("syncing"), working with files, and submitting files (in a "changelist"), and resolving files. Read this page first to get the most out of P4Web.

1. Setting up a workspace

2. Filling a workspace with files ("syncing")
   • Updating a workspace ("re-syncing")

3. Working on files
   • Editing files
   • Deleting files
   • Adding new files
   • Reverting files

4. Submitting a changelist
   • Submit errors
   • Resolving files
   • Re-submitting a changelist

The first thing you do in Perforce is to set up a personal client workspace on your local machine. You only have to do this once. You can't work with Perforce files until you've created a client workspace specification, or client spec.

In the P4Web control panel, select Go To->Edit Client Spec. Or click the "Edit Client Spec" shortcut button:

Edit Client Spec

Shortcut to "Edit Client Spec"

This brings up the Edit Client Spec page, which contains a form. The important field to enter is the Root, which tells Perforce where on your local filesystem to put your workspace, or where to copy depot files to on your local filesystem. For example, if you want your workspace to be located in the "c:\ws" path, enter "c:\ws" in the Root field.

After entering the workspace root, go to the bottom of the page and click Save. (There are other fields you can edit, but you can come back to them later when you have a better idea of how Perforce works.) You'll see the message "Client [name] saved." From this page, click the "Return to Browser" shortcut:

"Return to Browser" shortcut

If you ever need to change your client spec, just bring up this form again with Go To->Edit Client Spec.

Once you have set up your workspace you can fill it with files from the depot. In Perforce, this is called "synchronizing" your workspace, or "syncing" for short. To sync your workspace for the first time,

1. Look in the upper left corner of the control panel and make sure you're in the Path Browser. If you're not, click Go To->Path Browser in the control panel.

2. Beneath the Path Browser control panel you'll see the top level of the Perforce depot tree. Click on depot and path names to navigate down to the depot path you want to work on. Navigate down until the path shown is the one you want to sync. It will look something like this:

   Client view path:
   //depot/projects/gizmo/...

3. Click the "Sync to Head Revisions" shortcut button.

   Shortcut to "Sync to Head Revisions"

4. This displays a command result page that shows you which files are being copied from the depot onto your workspace. When the result page is completely loaded, your workspace is "in sync" with the depot. Return to the Path Browser where you'll see icons showing that your files are synced.

   	"Return to Browser" shortcut
   	"Synced File" icon

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.

Updating ("re-syncing") a workspace

After you sync your workspace it can eventually get out of date because other people are submitting changes to depot files. You can re-sync your workspace to update it. Navigate to the path you want to update and click the "Sync" shortcut:

Shortcut to "Sync Files"

When you sync, Perforce gets the files from the depot that are newer than the ones in your workspace. If you run 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. Files that have already been copied to your workspace will not be copied a second time.

You should use sync regularly to update your workspace with the latest revisions of files. The files you are working on will be untouched when you sync. Read on to find out more about this.

Working on Files

Note:

• Opening files does not affect files in the depot. All it does is allow you to work on files in your workspace.

• You can open a file individually, from its File Browser page. Navigate to the directory that contains the file, then click on the file. This puts you in the File Browser, where you can run commands on a single file. Most of the examples below describe opening a single file at a time.

• You can also open several files at once from the Path Browser page. Commands run from the Path Browser can operate on all the files at or below the current path level. Navigate to the path that contains the files you want to open, then run commands from there.

• Perforce tracks the files you're working on in a changelist. As you open files, they go in your changelist. You have to submit your changelist to get your changes into the depot. Before a changelist is submitted, it is described as "pending." Submitting changelists is described a little further on.

Editing files

To open a file for edit, navigate to its File Browser page and click the "Open for Edit" shortcut button. A page showing the result of the edit command will appear. Click the "Return to Browser" button to redisplay the File Browser page. You'll see a visual icon next to the file to remind you that you have it opened for edit.

	Shortcut to "Open for Edit"
	"Return to Browser" shortcut
	"Opened for Edit" icon

Once a file is opened for edit, it becomes writeable by you. Now you can use an editor or any other tool to modify the file.

Deleting files

If you want to delete a depot file, first you have to "open it for delete" in your workspace. To open a file for delete, navigate to its File Browser page and click the "Open for Delete" shortcut. A page showing the result of the delete command will appear. Click the "Return to Browser" shortcut to redisplay the File Browser page for the directory that contains this file. You'll see a visual icon next to the file to remind you that you have it opened for delete.

	Shortcut to "Open for Delete"
	"Return to Browser" shortcut
	"Opened for Delete" icon

When you open a file for delete, P4Web removes it from your workspace and lets the Perforce server know you are planning on deleting it from the depot. When you delete a file from Perforce, the file itself is not actually "deleted." The file remains in the depot, but it is marked as deleted at the head revision.

Adding new files

To add new files to the Perforce depot, first use Go To->Workspace root and use the Path Browser to navigate to the path under which the files reside. (The files must exist below your workspace root in order for you to add them to the depot.)

Next, from the Path Browser's control panel, select Run->Open files for add... In the form that appears, select "By path" and click "Continue". Now you'll see a list of the files in your workspace path that aren't already in the depot. If there are any in that list that you don't want to add, uncheck them.

Click the "Add New Files" button, then click the "Return to Browser" shortcut from the result page. The files you entered will now be listed in the Path Browser with visual icons showing that they are opened for add.

	Workspace root
	Add new files...
	"Return to Browser" shortcut
	"Opened for Add" icon

Opening files for add tells Perforce you plan to add them to the depot. It doesn't create the files, however. You must have done that previously, with an editor or any other tool.

Reverting files

Sometimes after opening files you realize you don't need to change them after all. In that case, you can use "Revert" to restore opened files to their original condition. You can use "Revert" either from the Path Browser or the File Browser. The former reverts all opened files in a particular path; the latter reverts a particular file.

The "Revert if Unchanged" shortcut can be used to automatically revert files you have opened for edit as long as you haven't changed them. Navigate to the path or file in question and click the "Revert if Unchanged" button. Then click "Return to Browser":

	"Opened for Edit" icon
	Shortcut to "Revert if Unchanged"
	"Return to Browser" shortcut

Neither files that you have modified nor files opened for add or delete can be reverted using a shortcut. To revert those files, navigate to the path or file in question and select Run->Revert from the menu bar. Click Revert to run the command after you've selected your options. From the result page, click the "Return to Browser" button:

Revert...

"Return to Browser" shortcut

Caution:

In the Revert options page, you must leave the "Restrict to unchanged files" checkbox blank if you want to revert files opened for add or delete. Files you have opened for add remain intact after they are reverted so you don't have to worry about losing them. However, P4Web overwrites files opened for edit when you run revert this way, discarding any workspace changes you have made to them. Use the "Selected Files" option in the form to de-select any files with changes you don't want discarded:

Restrict to unchanged files

Selected Files

As you open files 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 the "Submit Default Changelist" shortcut button. It's visible on the Path Browser and File Browser pages.

Shortcut to "Submit Default Changelist"

In the form that comes up, enter a description that explains why you are submitting these files. This description is stored permanently in Perforce and will be visible to anyone who looks at the history of any of the files in your changelist.

You don't have to fill in the Jobs field. It is used to associate jobs with changelists.

At the bottom of the form you'll see a checkbox list of all your opened files. If there are any you don't want to submit, uncheck them now. Then press the "Submit" button. A results page will show you whether or not your submit succeeded. After viewing the results, you can return to the Path or File Browser.

	"Return to Browser" shortcut

Note: If any of the files you submit have been changed by someone else first, you'll get a submit error, as described below. This is perfectly normal. When it happens all you have to do is resolve your files and re-submit your changelist.

Submit errors

Sometimes when you've been working on files, other people will have submitted changes to the same files. If you haven't re-synced 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'

Resolving files

Resolving files is how you merge 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 the opened copy of main.c in your workspace.

Note that files in your workspace don't actually need resolving until you either re-sync your workspace, or get a submit error trying to submit files that have been changed in the depot by someone else. You can tell which of your files need to be resolved by looking for the "Needs Resolve" icon on files listed in the Path Browser.

"Needs Resolve" icon

You can resolve your files with the "Resolve Interactively" shortcut.

Shortcut to "Resolve Interactively"

"Resolve Interactively" launches a separate window running the Perforce interactive resolve program. It prompts you through your unresolved files and lets you choose what to do. For each file, you'll see information 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]:

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

You can choose to skip any file and resolve it later. Your workspace file will remain untouched if you choose to skip the file.

Re-submitting a changelist

A submit error will cause your changelist to be assigned a number. After you've resolved the files that caused the submit error, you can re-submit your numbered changelist using Go To->Pending Changelists in the control panel. Click on the changelist number you want to submit. Now you can submit your changelist following the instructions in Submitting a Changelist.

Pending Changelists