Chapter 5
Perforce Basics:
Resolving File Conflicts

1. Ed opens file foo for edit.

2. Lisa opens the same file in her client for edit.

3. Ed and Lisa both edit their client workspace versions of foo.

4. Ed submits a changelist containing foo, and the submit succeeds.

5. Lisa submits a changelist with her version of foo; and her submit fails.

Resolving a file conflict is a two-step process: first the resolve is scheduled, then the resolve is performed. A resolve is automatically scheduled when a submit of a changelist fails because of a file conflict; the same resolve can be scheduled manually, without submitting, by syncing the head revision of a file over an opened revision within the client workspace. Resolves are always performed with p4 resolve.

Perforce also provides facilities for locking files when they are edited. This can eliminate file conflicts entirely.

RCS Format: How Perforce Stores File Revisions

Only the differences between revisions are stored

As an example, suppose that a Perforce depot has three revisions of file foo. The head revision (foo#3) looks like this:

Revision two might be stored as a symbolic version of the following:

And revision one might be a representation of this:

From these partial file descriptions, any file revision can be reconstructed. The reconstructed foo#1 would read

The RCS (Revision Control System) algorithm, developed by Walter Tichy, uses a notation for implementing this system that requires very little storage space and is quite fast. In RCS terminology, it is said that the full text of the head revisions are stored, along with the reverse deltas of each previous revision.

It is interesting to note that the full text of the first revision could be stored, with the deltas leading forward through the revision history of the file, but RCS has chosen the other path: the full text of the head revision of each file is stored, with the deltas leading backwards to the first revision. This is because the head revision is accessed much more frequently than previous file revisions; if the head revision of a file had to be calculated from the deltas each time it was accessed, any SCM utilizing RCS format would run much more slowly.

Use of "diff" to determine file revision differences

Because Perforce's diff always determines file deltas by comparing chunks of text between newline characters, it is by default only used with text files. If a file is binary, each revision is stored in full.

Scheduling Resolves of Conflicting Files

In slightly more technical terms, we'll call the file revision that was read into a client workspace the base file revision. If the base file revision for a particular file in a client workspace is not the same as the head revision of the same file in the depot, a resolve must be performed before the new file revision can be accepted into the depot.

Before resolves can be performed with p4 resolve, they must be scheduled; this can be done with p4 sync. An alternative is to submit a changelist that contains the newly conflicting files. If a resolve is necessary, the submit fails, and the resolve is scheduled automatically.

Why "p4 sync" to Schedule a Resolve?

• If the file does not exist in the client, or it is found in the client but is unopened, it is copied from the depot to the client.

• If the file has been deleted from the depot, it is deleted from the client.

• If the file has been opened in the client with p4 edit, the Perforce server can't simply copy the file onto the client: any changes that had been made to the current revision of the file in the client would be overwritten. Instead, a resolve is scheduled between the file revision in the depot, the file on the client, and the base file revision (the revision that was last read into the client).
  Example:  Scheduling resolves with p4 sync
  Ed is making a series of changes to the *.guide files in the elm doc subdirectory. He has retrieved the //depot/elm_proj/doc/*.guide files into his client and has opened the files with p4 edit. He edits the files, but before he has a chance to submit them, Lisa submits new versions of some of the same files to the depot. The versions Ed has been editing are no longer the head revisions, and resolves must be scheduled and performed for each of the conflicting files before Ed's edits can be accepted.
  Ed schedules the resolves with p4 sync //edk/doc/*.guide. Since these files are already open in the client, Perforce doesn't replace the client files. Instead, Perforce schedules resolves between the client files and the head revisions in the depot.
  Alternatively, Ed could have submitted the //depot/elm_proj/doc/*.guide files in a changelist; the file conflicts would cause the p4 submit to fail, and the resolves would be scheduled as part of the submission failure.

How Do I Know When a Resolve is Needed?

Another way of determining whether a resolve is needed is to run p4 sync -n filenames before performing the submit, using the files in the changelist as arguments to the command. If file conflict resolutions are necessary, p4 sync -n reports them. The advantage of this approach is that the files in the default changelist remain in the default changelist (that is, the default changelist will not be reassigned to a numbered changelist).

Performing Resolves of Conflicting Files

p4 resolve is interactive; a series of options are displayed for the user to respond to. The dialog looks something like this:

The remainder of this section explains what this means, and how to use this dialog.

File revisions used and generated by "p4 resolve"

The remainder of this chapter will use the terms theirs, yours, base, merge, and result to refer to the corresponding file revisions. The definitions given above are somewhat different when resolve is used to integrate branched files.

Types of conflicts between file revisions

• Is this line set the same in yours, theirs, and base?

• Is this line set the same in theirs and base, but different in yours?

• Is this line set the same in yours and base, but different in theirs?

• Is this line set the same in yours and theirs, but different in base?

• Is this line set different in all three files?

2 yours + 3 theirs + 1 both + 5 conflicting

How the merge file is generated

Thus, editing the Perforce-generated merge file is often as simple as opening the merge file, searching for the difference marker ">>>>", and editing that portion of the text. This isn't always the case, as it is often necessary to examine the changes made to theirs to make sure they're compatible with other changes that you made. This can be facilitated by calling p4 resolve with the -v flag; p4 resolve -v tells Perforce to generate difference markers for all changes made in either file being resolved, instead of only for changes that are in conflict between the yours and theirs files.

The "p4 resolve" options

Only a few of these options are visible on the command line, but all options are always accessible and can be viewed by choosing help. The merge file is generated by p4d's internal diff routine. But the differences displayed by dy, dt, dm, and d are generated by a diff internal to the Perforce client program, and this diff can be overridden by specifying an external diff in the P4DIFF environment variable.

The command line has the following format:

Perforce's recommended choice is displayed in brackets at the end of the command line. Pressing Return or choosing Accept will perform the recommended choice. The recommended command is chosen by Perforce by the following algorithm: if there were no changes to yours, accept theirs. If there were no changes to theirs, accept yours. Otherwise, accept merge.

Example:  Resolving File Conflicts

In the last example, Ed scheduled the doc/*.guide files for resolve. This was necessary because both he and Lisa had been editing the same files; Lisa had already submitted versions, and Ed needs to reconcile his changes with Lisa's. To perform the resolves, he types p4 resolve //depot/elm_proj/doc/*.guide, and sees the following:

/usr/edk/elm/doc/Alias.guide - merging //depot/elm_proj/doc/Alias.guide#5 Diff chunks: 4 yours + 2 theirs + 1 both + 1 conflicting Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [e]:

This is the resolve dialog for doc/Alias.guide, the first of the four doc/*.guide files. Ed sees that he's made four changes to the base file that don't conflict with any of Lisa's changes. He also notes that Lisa has made two changes that he's unaware of. He types dt (for "display theirs") to view Lisa's changes; he looks them over and sees that they're fine. Of most concern to him, of course, is the one conflicting change. He types e to edit the Perforce- generated merge file and searches for the difference marker ">>>>". The following text is displayed:

Acme Technology Mountain View, California >>>> ORIGINAL VERSION ==== THEIR VERSION 94041 ==== YOUR VERSION 98041 <<<<

He and Lisa have both tried to add a zip code to an address in the file, but Ed had typed it wrong. He edits this portion of the merge file so it reads as follows:

Acme Technology Mountain View, California 94041

The merge file is now acceptable to him: he's viewed Lisa's changes, seen that they're compatible with his own, and the only line conflict has been resolved. He quits from the editor and types am; the edited merge file is written to the client, and the resolve process continues on the next doc/*.guide file.

When a version of the file is accepted onto the client, the previous client file is overwritten, and the new client file must still be submitted to the depot. Note that it is possible for another user to have submitted yet another revision of the same file to the depot between the time p4 resolve completes and the time p4 submit is performed; in this case, it would be necessary to perform another resolve. This can be prevented by performing a p4 lock on the file before performing the resolve.

Using Flags with Resolve
to Automatically Accept Particular Revisions

Example:  Automatically accepting particular revisions of conflicting files

Ed has been editing the files in doc/*.guide, and knows that some of them will require resolving. He types p4 sync doc/*.guide, and all of these files that conflict with files in the depot are scheduled for resolve.

He then types p4 resolve -am, and the merge files for all scheduled resolves are generated, and those merge files that contain no line set conflicts are written to his client workspace.

He'll still need to manually resolve all the other conflicting files, but the amount of work he needs to do is substantially reduced.

Binary files and "p4 resolve"

Locking Files to Minimize File Conflicts

The clear benefit of p4 lock is that once a file is locked, the user who locked it experiences no further conflicts on that file, and will not need to resolve the file. However, this comes at a price, as other users will not be able to submit the file until the file is unlocked, and will have to do their own resolves once they submit their revision. Under most circumstances, a user who locks a file is essentially saying to other users "I don't want to deal with any resolves; you do them."

There is an exception to this rule: Perforce also has a +l file type modifier to support exclusive-open. If you have a +l file open for edit, other users who attempt to edit the file will receive an error message.

The difference between p4 lock and +l is that p4 lock allows anyone to open a file for edit, but only the person who locked the file may submit it. By contrast, a file of type +l allows only one person to open the file for edit in the first place.

Preventing multiple resolves with p4 lock

1. Ed opens file foo for edit.

2. Lisa opens the same file in her client for edit.

3. Ed and Lisa both edit their client workspace versions of foo.

4. Ed submits a changelist containing that file, and his submit succeeds.

5. Lisa submits a changelist with her version of the file; her submit fails because of file conflicts with the new depot's foo.

6. Lisa starts a resolve.

7. Ed edits and submits a new version of the same file.

8. Lisa finishes the resolve and attempts to submit; the submit fails and must now be merged with Ed's latest file.

   ...and so on

1. Before scheduling a resolve, lock the file.

2. Then sync the file, resolve the file, and submit the file.

Locked files appear in the output of p4 opened with an indication of *locked*. On UNIX, you can find all locked files you have open with the following command:

p4 opened | grep "*locked*"

Preventing multiple checkouts with +l files

You can change a file's type to exclusive-open by reopening it with the +l modifier. For instance:

p4 reopen -t binary+l file.gif

If you find this style of work to be useful, you may want to ask your Perforce administrator to use the p4 typemap command (documented in the Perforce Command Reference) to ensure that all files matching a file specification (for instance, //depot/.../*.gif for all .gif files) are assigned type +l by default.

Resolves and Branching

Resolve Reporting

The reporting chapter (Chapter 11, Reporting and Data Mining) has a longer description of each of these commands. p4 help provides a complete listing of the many flags for these reporting commands.