2.1. An Overview

In Perforce, working on files involves setting up and synchronizing a workspace, adding and working on files, resolving parallel changes (if necessary), and submitting changes to the depot:

Setting up a workspace

The first thing you do before you can work on files is define a client workspace for yourself. A client workspace specification, or client spec, tells Perforce where in your local filesystem you want your workspace to be rooted. It has a view that defines the areas of the depot you want access to, and maps them to directories beneath the workspace root. Once you've set up your workspace, you can work on files.

Adding new files

If you have files in your workspace already—files that you created or moved there yourself—you can add them to the depot. In Perforce, any change you make—adding files , for example—involves two Perforce operations. First you open your workspace files, indicating whether you want to add, change, or delete them. Then, after making changes locally, you submit files to the depot.

Don't confuse Perforce's idea of open with the idea of opening files in applications. In Perforce, an open file is a file you intend to change. Opening a file with Perforce does not launch an application. And an application—Word or Vim, for example—can open a workspace file whether or not Perforce considers it open.

Synchronizing your workspace

To work on files that are already in the depot, you must first synchronize your workspace (see Figure 2-1). This step gets local copies of the latest depot files. Your workspace is considered to be "in sync" when all the files in it match their depot counterparts.

Figure 2-1. Synchronizing a workspace

Working on files

By default, Perforce creates nonwritable files in your workspace. This is meant as a gentle reminder to you that these files are under its control. Although you're free to do what you want in your workspace, including changing file permissions, the preferred method is to let Perforce know what you're up to by opening files first. You open files with commands that indicate what you plan to do—add, edit, or delete, for example. Perforce updates the workspace per your intent: files you open for editing are made writable, for example, and files you open for deletion are removed from the workspace.

Files in the depot are not affected when you open workspace files. Perforce doesn't automatically lock depot files, but you have the option of locking them explicitly. Also, while opening files first is the preferred method, you can modify files first and open them after the fact. Thus you don't have to be on the network, connected to Perforce, to modify your workspace files.

As you work, you always have the option of reverting opened files to their unmodified state. Perforce reverts workspaces files by replacing them with fresh copies from the depot, effectively discarding any changes you made.

Resolving parallel changes

You can, and should, resynchronize your workspace every now and then to update your local files. Synchronizing replaces stale files with the newest depot versions. It does not, however, affect the files you're working on, except to mark them unresolved. When you're ready, you can resolve them to reconcile parallel changes.

Resolving files is a Perforce operation in which you choose whether you want to merge, copy, or ignore the newer depot versions. If you choose to resolve files by merging them, Perforce will do as much automatic merging as it can. It can't automatically merge files with conflicting changes, however—those you'll have to do individually. You can use one Perforce's merge tools, or a merge tool of your own choosing, to merge files individually.

Submitting changes to the depot

As you open files, Perforce builds up what's called a pending changelist. This is the set of files you plan to submit as a single unit of work. Although we speak of submitting files, you really submit the pending changelist. At your option, you can have more than one pending changelist in your workspace. By juggling opened files between them you can control which files will be submitted together.

You can't submit files if there are newer versions of them in the depot. In other words, Perforce won't let you inadvertently overwrite other peoples' changes. Instead, you'll have to resolve them and try submitting them again.

Files successfully submitted are sent from your workspace to the depot and stored as new revisions (see Figure 2-2). Your submitted changelist becomes an event in the evolution of the depot, recorded for eternity.