|
|
Chapter 5
Perforce Basics: Resolving File Conflicts
|
|
File conflicts can occur when two users edit and submit two versions of the same file. Conflicts can occur in a number of ways, but the situation is usually a variant of the following:
- Ed opens file foo for edit;
- Lisa opens the same file in her client for edit;
- Ed and Lisa both edit their client workspace versions of foo;
- Ed submits a changelist containing foo, and the submit succeeds;
- Lisa submits a changelist with her version of foo; her submit fails.
If Perforce were to accept Lisa's version into the depot, the head revision would contain none of Ed's changes. Instead, the changelist is rejected and a resolve must be performed. The resolve process allows a choice to be made: Lisa's version can be submitted in place of Ed's, Lisa's version can be dumped in favor of Ed's, a Perforce-generated merged version of both revisions can be submitted, or the Perforce-generated merged file can be edited and then submitted.
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
|
|
Perforce uses RCS format to store its text file revisions; binary file revisions are always saved in full. If you already understand what this means, you can skip to the next section of this chapter; the remainder of this section explains how RCS format works.
Only the Differences Between Revisions are Stored
A single file might have hundreds, even thousands, of revisions. Every revision of a particular file must be retrievable, and if each revision was stored in full, disk space problems could occur: one thousand 10KB files, each with a hundred revisions, would use a gigabyte of disk space. The scheme used by most SCM systems, including Perforce, is to save only the latest revision of each file, and then store the differences between each file revision and the one previous.
As an example, suppose that a Perforce depot has three revisions of file foo. The head revision (foo#3) looks like this:
foo#3: This is a test of the emergency broadcast system
|
Revision two might be stored as a symbolic version of the following:
foo#2: line 3 was "urgent"
|
And revision one might be a representation of this:
foo#1: line 4 was "system"
|
From these partial file descriptions, any file revision can be reconstructed. The reconstructed foo#1 would read
Reconstructed foo#1: This is a test of the urgent system
|
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
RCS uses the "GNU diff" algorithm to determine the differences between two versions of the same file; p4d contains its own diff routine which is used by Perforce servers to determine file differences when storing deltas. 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
|
|
Whenever a file revision is to be submitted that is not an edit of the file's current head revision, there will be a file conflict, and this conflict must be resolved.
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 will fail, and the resolve will be scheduled automatically.
|
Why "p4 sync" to Schedule a Resolve?
|
|
Remember that the job of p4 sync is to project the state of the depot onto the client. Thus, when p4 sync is performed on a particular file:
- 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; 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?
|
|
p4 submit will fail if it determines that any of the files in the submitted changelist need to be resolved, and the error message will include the names of the files that need resolution. If the changelist provided to p4 submit was the default changelist, it will be assigned a number, and this number must be used in all future references to the changelist. (Numbered changelists are discussed in chapter 7)
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 will report them. The only advantage of this scheme over viewing the submit error is that the default changelist will not be assigned a number.
|
Performing Resolves of Conflicting Files
|
|
File conflicts are fixed with p4 resolve [filenames]. Each file provided as an argument to p4 resolve is processed separately. p4 resolve starts with three revisions of the same file and generates a fourth version; the user can accept any of these revisions in place of the current client file, and can edit the generated version before accepting it. The new revisions must then be submitted with p4 submit.
p4 resolve is interactive; a series of options are displayed for the user to respond to. The dialog looks something like this:
/usr/edk/elm/doc/answer.1 - merging //depot/elm_proj/doc/answer.1#5 Diff chunks: 4 yours + 2 theirs + 1 both + 1 conflicting Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [e]:
|
The remainder of this section explains what this means, and how to use this dialog.
File Revisions Used and Generated by "p4 resolve"
p4 resolve [filenames] starts with three revisions of the same file, generates a new version that merges elements of all three revisions, allows the user to edit the new file, and writes the new file (or any of the original three revisions) to the client. The file revisions used by p4 resolve are these:
yours
|
The newly-edited revision of the file in the client workspace. This file is overwritten by result once the resolve process is complete.
|
theirs
|
The revision in the depot that the client revision conflicts with. Usually, this is the head revision, but p4 sync can be used to schedule a resolve with any revision between the head revision and base.
|
base
|
The file revision in the depot that yours was edited from. Note that base and theirs are different revisions; if they were the same, there would be no reason to perform a resolve.
|
merge
|
File variation generated by Perforce from theirs, yours, and base.
|
result
|
The file resulting from the resolve process. result is written to the client workspace, overwriting yours, and must subsequently be submitted by the user. The instructions given by the user during the resolve process determine exactly what is contained in this file. The user can simply accept theirs, yours, or merge as the result, or can edit merge to have more control over the result.
|
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 (see "Branching" on page 65).
Types of Conflicts Between File Revisions
The diff program that underlies the Perforce resolve mechanism determines differences between file revisions on a line-by-line basis. Once these differences are found, they are grouped into chunks: for example, three new lines that are adjacent to each other are grouped into a single chunk. Yours and theirs are both generated by a series of edits to base; for each set of lines in yours, theirs, and base, p4 resolve asks the following questions:
- 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?
Any line sets that are the same in all three files don't need to be resolved. The number of line sets that answer the other four questions are reported by p4 resolve in this form:
2 yours + 3 theirs + 1 both + 5 conflicting
In this case, two line sets are identical in theirs and base but are different in yours; three line sets are identical in yours and base but are different in theirs; one line set was changed identically in yours and theirs; and five line sets are different in yours, theirs, and base.
How the Merge File is Generated
p4 resolve generates a preliminary version of the merge file, which can be accepted as is, edited and then accepted, or rejected. A simple algorithm is followed to generate this file: any changes found in yours, theirs, or both yours and theirs are applied to the base file and written to the merge file; and any conflicting changes will appear in the merge file in the following format:
>>>> ORIGINAL VERSION foo#n (text from the original version) ==== THEIR VERSION foo#m (text from their file) ==== YOUR VERSION foo (text from your file) <<<<
|
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. However, this isn't always the case; it's 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
The p4 resolve command offers the following options:
Option
|
Short Meaning
|
What it Does
|
---|
e
|
edit merged
|
Edit the preliminary merge file generated by Perforce
|
ey
|
edit yours
|
Edit the revision of the file currently in the client
|
et
|
edit theirs
|
Edit the revision in the depot that the client revision conflicts with (usually the head revision). This edit is read-only.
|
|
|
|
dy
|
diff yours
|
Diff line sets from yours that conflict with base
|
dt
|
diff theirs
|
Diff line sets from theirs that conflict with base
|
dm
|
diff merge
|
Diff line sets from merge that conflict with base
|
d
|
diff
|
Diff line sets from merge that conflict with yours
|
m
|
merge
|
Invoke the command P4MERGE base theirs yours merge. To use this option, you must set the environment variable P4MERGE to the name of a third-party program that merges the first three files and writes the fourth as a result.
|
?
|
help
|
Display help for p4 resolve
|
s
|
skip
|
Don't perform the resolve right now.
|
ay
|
accept yours
|
Accept yours into the client workspace as the resolved revision, ignoring changes that may have been made in theirs.
|
at
|
accept theirs
|
Accept theirs into the client workspace as the resolved revision. The revision that was in the client workspace is trashed.
|
am
|
accept merge
|
Accept merge into the client workspace as the resolved revision. The version originally in the client workspace is trashed.
|
a
|
accept
|
if theirs is identical to base, accept yours;
if yours is identical to base, accept theirs;
if yours and theirs are different from base, and there are no conflicts between yours and theirs; accept merge;
otherwise, there are conflicts between yours and theirs, so skip this file
|
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:
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [am]:
|
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:
Glyphic 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; Ed had typed it wrong. He edits this portion
of the merge file so it reads as follows:
Glyphic 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 Non-Interactively Accept Particular Revisions
|
|
Five optional p4 resolve flags tell the command to work non-interactively; when these flags are used, particular revisions of the conflicting files will be automatically accepted.
"p4 resolve" flag
|
Meaning
|
---|
-ay
|
Automatically accept yours.
|
-at
|
Automatically accept theirs. Use this option with caution; the file revision in the client workspace will be overwritten with no chance of recovery.
|
-am
|
Automatically accept the Perforce-recommended file revision
:if theirs is identical to base, accept yours;
if yours is identical to base, accept theirs;
if yours and theirs are different from base, and there are no conflicts between yours and theirs; accept merge;
otherwise, there are conflicts between yours and theirs, so skip this file.
|
-af
|
Accept the Perforce-recommended file revision, no matter what. If this option is used, the resulting file in the client should be edited to remove any difference markers.
|
-as
|
if theirs is identical to base, accept yours;
if yours is identical to base, accept theirs;
otherwise skip this file.
|
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; all of these files that conflict with files in the depot are scheduled for resolve. He then
types p4 resolve -am; 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"
If any of the three file revisions participating in the merge are binary instead of text, a three-way merge is not possible. Instead, p4 resolve performs a two-way merge: the two conflicting file versions are presented, and you can edit and choose between them.
|
Locking Files to Minimize File Conflicts
|
|
Once open, a file can be locked with p4 lock so that only the user who locked the file can submit the next revision of that file to the depot. Once the file is submitted, it is automatically unlocked. Locked files can also be unlocked manually by the locking user with p4 unlock.
The clear benefit of p4 lock is that once a file is locked, the user who locked it will experience no further conflicts on that file, and will not need to resolve the file. But this comes at a price: 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.", but there is an exception to this rule.
Preventing Multiple Resolves with File Locking
Without file locking, there is no guarantee that the resolve process will ever end. The following scenario demonstrates the problem:
- Ed opens file foo for edit;
- Lisa opens the same file in her client for edit;
- Ed and Lisa both edit their client workspace versions of foo;
- Ed submits a changelist containing that file, and his submit succeeds;
- Lisa submits a changelist with her version of the file; her submit
- fails because of file conflicts with the new depot's foo;
- Lisa starts a resolve;
- Ed edits and submits a new version of the same file;
- Lisa finishes the resolve and attempts to submit; the submit fails and must now be merged with Ed's latest file.
<etc...>
File locking can be used in conjunction with resolves to avoid this sort of headache. The sequence would be implemented as follows: before scheduling a resolve, lock the file. Then sync the file, resolve the file, and submit the file. New versions can't be submitted by other users until the resolved file is either submitted or unlocked.
|
Resolves and Branching
|
|
Files in separate codelines can be integrated with p4 resolve; discussion of resolving branched files begins in the Branching chapter (chapter 9).
|
Resolve Reporting
|
|
Four reporting commands are related to file conflict resolution: p4 diff, p4 diff2, p4 sync -n, and p4 resolved.
Command
|
Meaning
|
---|
p4 diff [filenames]
|
Runs a diff program between the file revision currently in the client and the revision that was last gotten from the depot. If the file is not open for edit in the client, the two file revisions should be identical, so p4 diff will fail. Comparison of the revisions can be forced with p4 diff -f, even when the file in the client is not open for edit
Although p4 diff runs a diff routine internal to Perforce, this routine can be overridden by specifying an external diff in the P4DIFF environment variable.
|
p4 diff2 file1 file2
|
Runs p4d's diff subroutine on any two Perforce depot files. The specified files can be any two file revisions, even revisions of entirely different files.
The diff routine used by p4d cannot be overridden.
|
p4 sync -n [filenames]
|
Reports what the result of running p4 sync would be, without actually performing the sync. This is useful to see which files have conflicts and need to be resolved.
|
p4 resolved
|
Reports which files have been resolved but not yet submitted.
|
The reporting chapter (chapter 11) has a longer description of each of these commands; p4 help provides a complete listing of the many flags for these reporting commands.
|
|
|
Please send comments and questions about this manual to
[email protected].
Copyright 1997, 1998, 1999, 2000 Perforce Software. All rights reserved.
Last updated: 10/09/00
|