Chapter 5
Perforce Basics:
Resolving File Conflicts

Consider the following scenario:

1. Ed opens file.c for edit in his client workspace.

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

3. Ed and Lisa both work on their respective versions of file.c.

4. Ed submits a changelist containing his version of file.c, and the submit succeeds.

5. Lisa submits a changelist with her version of file.c. Her submit fails because of a file conflict with Ed's version.

• Submit her version of the file, overriding Ed's version.

• Discard her changes to the file in favor of Ed's version.

• Generate a merged version of the file that contains both sets of changes, and submit the merged version.

• Review and edit the merged version of the file before submitting it.

The Perforce server automatically schedules a resolve whenever you submit a changelist fails due to a file conflict. You can also schedule a resolve manually by syncing the head revision of a file over an opened revision within your client workspace. To perform a resolve, use the p4 resolve command. Perforce also provides facilities to prevent file conflicts by locking files when they are edited.

Scheduling Resolves of Conflicting Files

The file revision that was most recently synced to your client workspace is the base file revision. If the base file revision for a particular file in your workspace is not the same as the head revision of the same file in the depot, you must perform a resolve the new file revision can be accepted into the depot.

Before you can perform a resolve with the p4 resolve command, you must schedule the resolve. You can schedule a resolve with p4 sync, or by submitting a changelist that contains the newly conflicting files. If a resolve is necessary, your submit fails, and the resolve is automatically scheduled for you.

Why "p4 sync" to schedule a resolve?

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

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

• If you have opened the file in your workspace with p4 edit, the Perforce server cannot copy the file into your workspace, because doing so would overwrite any changes you had made. The Perforce server schedules a resolve between the file revision in the depot, the revision in your workspace, and the base file revision (that is, the revision you last synced to your workspace).
  Example:  Scheduling resolves with p4 sync
  Ed is making a series of changes to the *.guide files in the elm doc subdirectory. He has synced the //depot/elm_proj/doc/*.guide files to his workspace 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. Because these files are already open in his workspace, his workspace files are not overwritten. The p4 client program schedules the resolves between Ed's workspace 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 have caused the p4 submit to fail, and the resolves would have been scheduled as a result of the submission failure.

How do I know when a resolve is needed?

Another way to determine if a resolve is needed is to run p4 sync -n filename before performing the submit, using the open files in your changelist as the arguments to the command. If resolves on files are necessary, p4 sync -n reports them. If you use this approach, the files in your default changelist remain in your default changelist (that is, you do not need to create a numbered changelist).

Performing Resolves of Conflicting Files

The p4 resolve process starts with three revisions of the same file and generates a fourth version; you can accept any of these versions in place of the file in your workspace, and you can edit the generated version before accepting it into your workspace. Whatever version of the file you choose, after you have resolved the conflict, use p4 submit to submit the file to the depot.

The p4 resolve command is interactive, and presents a series of prompts:

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

File revisions used and generated by "p4 resolve"

The file revisions used by p4 resolve are as follows:

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

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. You can speed this process 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 conflict between the yours and theirs files. When resolving conflicts, remember that the absence of conflicting diff chunks does not imply correctness of code.

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 algorithm built into the p4 client program. To use a third-party diff utility in place of the p4 client program's diff algorithm, specify the third-party utility in the P4DIFF environment variable.

The p4 resolve prompt has the following format:

A recommended choice is displayed in brackets at the end of the prompt. Pressing Return or choosing Accept accepts the default option. The recommended option is chosen according 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 into your workspace, your previous workspace file is overwritten, and you must still submit the revised file to the depot. 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 when you call p4 submit; if this has happened, you will have to perform another resolve. (You can prevent this from happening by performing a p4 lock on the file before starting the resolve. See "Preventing multiple resolves with p4 lock" on page 76 for details.)

Command line flags to automate the resolve process

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 benefit of p4 lock is that after a file is locked, the user who locked it experiences no further conflicts on that file, and never needs to resolve the file. This benefit comes at a price: other users can open the file for edit, but are unable to submit changes affecting 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 supports a +l file type modifier to support exclusive-open (pessimistic locking). If you have a +l file open for edit, other users who attempt to edit the file receive an error message.

The difference between p4 lock and +l is that p4 lock permits anyone to open a file for edit, but only the person who locked the file can submit a changelist containing that file to the depot. By contrast, files of type +l can be opened for edit by only one user at a time.

Preventing multiple resolves with p4 lock

1. Ed opens file file for edit.

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

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

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

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

Your Perforce administrator can use the p4 typemap command (see the Perforce Command Reference) to ensure that all files matching a file specification (or even all files sitewide) 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. Use the p4 help command for a complete listing of the flags and options available with these reporting commands.