P4Web User Guide - Getting Started with Perforce and P4Web

P4Web Release 2005.1 User Guide
[Getting Started] [How To...] [Browser Tips] [Glossary] [Road Map]

Getting Started with Perforce and P4Web

This page is for users new to Perforce and P4Web. It describes how to use P4Web in Standard mode 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.

Setting up a Workspace

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.

Select the Clients tab. At the top of that page, click on the Edit current client link.

This brings up the Edit Client 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."

If you ever need to change your client spec, just bring up this form again using the Clients tab.

Filling a workspace ("syncing")

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,

Select the Files tab. If you do not see a Tree view of the depot, click to display it.
Navigate through the Tree to the depot path you want to work on. The current path is shown in the header at the top of the page. Navigate down until the path shown is the one you want to sync. It will look something like this:

Current path: //depot/projects/gizmo/
Click the "Sync to Head Revisions" shortcut button.

Shortcut to "Sync to Head Revisions"
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 Tree view where you'll see icons showing that your files are synced.

"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

Once you have synced your workspace, you can work on files. You can edit files, add files, and delete files, but first you must "open" them for these operations. You can also revert opened files to their original state.

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, by navigating to the directory that contains the file, then clicking on the file. You can then run commands on just that file. Most of the examples below describe opening a single file at a time.
You can also open several files at once by navigating to the path that contains the files you want to open, then running commands from there. Commands run from the directory level can operate on all the files at or below the current path level.
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 that file and click the "Open for Edit" shortcut button. A page showing the result of the edit command will appear. You can return to the Tree view to see a visual icon next to the file to remind you that you have it opened for edit.

Shortcut to "Open for Edit"

"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

To delete a depot file, first you have to "open it for delete" in your workspace. To open a file for delete, navigate to the file and click the "Open for Delete" shortcut. A page showing the result of the delete command will appear. In the Tree view, 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"

"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, you will need to be in the Workspace Tree. To do this, first select the Files tab and then click the "Display tree view" shortcut.

Shortcut to "Display tree view"

If the label at the top of the tree says Depot Tree, click the Switch to workspace tree link. If it says Workspace Tree, you're in the right place. (The files must exist below your workspace root in order for you to add them to the depot.)

Select Open for add... from the pulldown menu.

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. The files you entered will now be listed in the Tree view with visual icons showing that they are opened for add.

"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 a folder or file level. 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.

"Opened for Edit" icon

Shortcut to "Revert if Unchanged"

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 Revert... from the pulldown menu. Click Revert to run the command after you've selected your options.

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

Submitting a changelist

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.

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 click the "Submit" button. A results page will show you whether or not your submit succeeded.

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'

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.

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

"Needs Resolve" icon

You can resolve your files with the Resolve... option in the pulldown menu. Selecting this takes you to the Resolve options page.

Select "Interactively" to launch a resolve application in a separate window. If you have specified a resolve program to use with Perforce, P4Web launches that. If not, the default Perforce resolve program is launched. 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

...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. If there are no conflicting diffs (differences), 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 edited result.

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 by selecting the Pending tab and clicking on the changelist number you want to submit. Now you can submit your changelist following the instructions in Submitting a Changelist.