Previous Table of Contents Index Next
Perforce 2009.2: P4 User's Guide



Chapter 5
This chapter tells you how to work in a team development environment, where multiple users who are working on the same files might need to reconcile their changes.
In settings where multiple users are working on the same set of files, conflicts can occur. Perforce enables your team to work on the same files simultaneously and resolve any conflicts that arise. For example, conflicts occur if two users change the same file (the primary concern in team settings) or you edit a previous revision of a file rather than the head revision.
When you attempt to submit a file that conflicts with the head revision in the depot, Perforce requires you to resolve the conflict. Merging changes from a development branch to a release branch is another typical task that requires you to resolve files.
To prevent conflicts, Perforce enables you to lock files when they are edited. However, locking can restrict team development. Your team needs to choose the strategy that maximizes file availability while minimizing conflicts. For details, refer to Locking files.
You might prefer to resolve files using graphical tools like P4V, the Perforce Visual Client, and its associated visual merge tool P4Merge.
How conflicts occur
File conflicts can occur when two users edit and submit two versions of the same file. Conflicts can occur in a number of ways, for example:
1.
Bruno opens //depot/dev/main/jam/command.c#8 for edit.
2.
3.
Bruno and Gale both edit //depot/dev/main/jam/command.c#8.
4.
Bruno submits a changelist containing //depot/dev/main/jam/command.c, and the submit succeeds.
5.
Gale submits a changelist with her version of //depot/dev/main/jam/command.c. Her submit fails.
If Perforce accepts Gale's version into the depot, her changes will overwrite Bruno's changes. To prevent Bruno's changes from being lost, the Perforce server rejects the changelist and schedules the conflicting file to be resolved. If you know of file conflicts in advance and want to schedule a file for resolution, sync it. Perforce detects the conflicts and schedules the file for resolution.
How to resolve conflicts
To resolve a file conflict, you determine the contents of the files you intend to submit by issuing the p4 resolve command and choosing the desired method of resolution for each file. After you resolve conflicts, you submit the changelist containing the files.
If you open a file for edit, then sync a subsequently submitted revision from the depot, Perforce requires you to resolve to prevent your own changes from being overwritten by the depot file.
By default, Perforce uses its diff program to detect conflicts. You can configure a third-party diff program. For details, see Diffing files.
To resolve conflicts and submit your changes, perform the following steps:
1.
Sync the files (for example p4 sync //depot/dev/main/jam/...). Perforce detects any conflicts and schedules the conflicting files for resolve.
2.
Issue the p4 resolve command and resolve any conflicts. See Options for resolving conflicts for details about resolve options.
3.
4.
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 choose between them or edit the one in your workspace before submitting the changelist.
Your, theirs, base and merge files
The p4 resolve command uses the following terms during the merge process.
The revision in the depot, edited by another user, that yours conflicts with. (Usually the head revision, but you can schedule a resolve with another revision using p4 sync.)
The file revision in the depot that yours and theirs were edited from (the closest common ancestor file).
The file generated by Perforce from theirs, yours, and base.
Options for resolving conflicts
To specify how a conflict is to be resolved, you issue the p4 resolve command, which displays a dialog for each file scheduled for resolve. The dialog describes the differences between the file you changed and the conflicting revision. For example:
p4 resolve //depot/dev/main/jam/command.c
c:\bruno_ws\dev\main\jam\command.c - merging //depot/dev/main/jam/command.c#9
Diff chunks: 4 yours + 2 theirs + 1 both + 1 conflicting
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) e:
The differences between each pair of files are summarized by p4 resolve. Groups of lines (chunks) in the yours, theirs, and base files can differ in various ways. Chunks can be:
Diffs: different between two of the three files: yours, theirs, or base
Conflicts: different in all three files
In the preceding example:
Four chunks are identical in theirs and base but are different in yours.
Two chunks are identical in yours and base but are different in theirs.
One chunk is different in yours, theirs, and base.
Perforce's recommended choice is displayed at the end of the command line. Pressing ENTER or choosing Accept performs the recommended choice.
You can resolve conflicts in three basic ways:
The preceding options are interactive. You can also specify resolve options on the p4 resolve command line, if you know which file you want to accept. For details, see Resolve command-line flags.
To reresolve a resolved but unsubmitted file, specify the -f flag when you issue the p4 resolve command. You cannot reresolve a file after you submit it.
The following sections describe the resolve options in more detail.
Accepting yours, theirs, or merge
To accept a file without changing it, specify one of the following options.
Accept recommended file
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.
If you edited the merge file (by selecting e from the p4 resolve dialog), accept the edited version into the client workspace. The version in the client workspace is overwritten.
Accept merge
Accept merge into the client workspace as the resolved revision. The version in the client workspace is overwritten.
Accept theirs
Accept theirs into the client workspace as the resolved revision. The version in the client workspace is overwritten.
Accept yours
Accept yours into the client workspace as the resolved revision, ignoring changes that might have been made in theirs.
Accepting yours, theirs, edit, or merge overwrites changes, and the generated merge file might not be precisely what you want to submit to the depot. The most precise way to ensure that you submit only the desired changes is to use a merge program or edit the merge file.
Editing the merge file
To resolve files by editing the merge file, choose the e option. Perforce launches your default text editor, displaying the merge file. In the merge file, diffs and conflicts appear in the following format:
>>>> ORIGINAL file#n
(text from the original version)
==== THEIR file#m
(text from their file)
==== YOURS file
(text from your file)
<<<<
To locate conflicts and differences, look for the difference marker ">>>>" and edit that portion of the text. Examine the changes made to theirs to make sure that they are compatible with your changes. Make sure you remove all conflict markers before saving. After you make the desired changes, save the file. At the p4 resolve prompt, choose ay.
By default, only the conflicts between the yours and theirs files are marked. To generate difference markers for all differences, specify the -v flag when you issue the p4 resolve command.
Merging to resolve conflicts
A merge program displays the differences between yours, theirs, and the base file, and enables you to select and edit changes to produce the desired result file. To configure a merge program, set P4MERGE to the desired program. To use the merge program during a resolve, choose the m option. For details about using a specific merge program, consult its online help.
After you merge, save your results and exit the merge program. At the p4 resolve prompt, choose am.
Full list of resolve options
The p4 resolve command offers the following options.
Accept automatically
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.
If you edited the merge file (by selecting e from the p4 resolve dialog), accept the edited version into the client workspace. The version in the client workspace is overwritten.
Accept merge
Accept merge into the client workspace as the resolved revision. The version in the client workspace is overwritten.
Accept theirs
Accept theirs into the client workspace as the resolved revision. The version in the client workspace is overwritten.
Accept yours
Accept yours into the client workspace as the resolved revision, ignoring changes that might have been made in theirs.
Show diffs between merge and yours.
Diff merge
Show diffs between merge and base.
Diff theirs
Show diffs between theirs and base.
Diff yours
Show diffs between yours and base.
Edit theirs
Edit the revision in the depot that the client revision conflicts with (usually the head revision). This edit is read-only.
Edit yours
Invoke the command P4MERGE base theirs yours merge. To use this option, you must set P4MERGE to the name of a third-party program that merges the first three files and writes the fourth as a result.
The merge file is generated by the Perforce server, but the differences displayed by dy, dt, dm, and d are generated by the client machine's diff program. To configure another diff program to be launched when you choose a d option during a resolve, set P4DIFF. For more details, see Diffing files.
Example: Resolving file conflicts
To resolve conflicts between his work on a Jam readme file and Earl's work on the same file, Bruno types p4 resolve //depot/dev/main/jam/README and sees the following:
Diff chunks: 0 yours + 0 theirs + 0 both + 1 conflicting
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) e: e
Bruno sees that that he and Earl have made a conflicting change to the file. He types e to edit the merge file and searches for the difference marker ">>>>". The following text is displayed:
Jam/MR (formerly "jam - make(1) redux")
/+\
>>>> ORIGINAL README#26
    +\ Copyright 1993, 1997 Christopher Seiwald.
==== THEIRS README#27
    +\ Copyright 1993, 1997, 2004 Christopher Seiwald.
==== YOURS README
    +\ Copyright 1993, 1997, 2005 Christopher Seiwald.
<<<<
    \+/
Bruno and Earl have updated the copyright date differently. Bruno edits the merge file so that the header is correct, exits from the editor and types am. The edited merge file is written to the client workspace, and he proceeds to resolve the next file.
When a version of the file is accepted during a resolve, the file in the workspace is overwritten, and the new client file must still be submitted to the depot. New conflicts can occur if new versions of a file are submitted after you resolve but before you submit the resolved files. This problem can be prevented by locking the file before you perform the resolve. For details, see Locking files.
Resolve command-line flags
The following p4 resolve flags enable you to resolve directly instead of interactively. When you specify one of these flags in the p4 resolve command, files are resolved as described in the following table.
Accept yours.
Accept theirs. Use this option with caution, because the file revision in your client workspace is overwritten with the head revision from the depot, and you cannot recover your changes.
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 con­flicts between yours and theirs, accept merge.
Otherwise, there are conflicts between yours and theirs, so skip this file, leaving it unresolved.
Accept the recommended file revision, even if conflicts remain. If this option is used, edit the resulting file in the workspace to remove any difference markers.
If theirs is identical to base, accept yours.
If yours is identical to base, accept theirs.
Example: Automatically accepting particular revisions of conflicting files
Bruno has been editing the documentation files in /doc and knows that some of them 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 any conflicting files, but the amount of work he needs to do is substantially reduced.
Resolve reporting commands
The following reporting commands are helpful when you are resolving file conflicts.
p4 diff [filenames]
Diffs the file revision in the workspace with the last revision you synced, to display changes you have made.
p4 diff2 file1 file2
When you diff depot files, the Perforce server uses its own diff program, not the diff program configured by setting P4DIFF.
p4 sync -n [filenames]
Locking files
After you open a file, you can lock it to prevent other users from submitting it before you do. The benefit of locking a file is that conflicts are prevented, but when you lock a file, you might prevent other team members from proceeding with their work on that file.
Preventing multiple resolves by locking files
Without file locking, there is no guarantee that the resolve process ever ends. The following scenario demonstrates the problem:
1.
2.
3.
4.
5.
6.
7.
8.
...and so on.
To prevent such problems, you can lock files, as follows.
1.
2.
3.
4.
5.
To list open locked files on UNIX, issue the following command:
p4 opened | grep "*locked*"
Preventing multiple checkouts
To ensure that only one user at a time can work on the file, use the +l (exclusive-open) file type modifier. For example:
p4 reopen -t binary+l file
Although exclusive locking prevents concurrent development, for some file types (binary files), merging and resolving are not meaningful, so you can prevent conflicts by preventing multiple users from working on the file simultaneously.
Your Perforce administrator can use the p4 typemap command to ensure that all files of a specified type (for instance, //depot/.../*.gif for all .gif files) can only be opened by one user at a time. See the Perforce Command Reference for details.
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 can submit it. By contrast, a file of type +l prevents more than one user from opening the file.
 


Previous Table of Contents Index Next

Perforce 2009.2: P4 User's Guide
Copyright 2005-2009 Perforce Software.