Perforce 2008.1 P4 User's Guide


<< Previous Chapter Managing Files and Changelists	Table of Contents Index Perforce on the Web	Next Chapter >> Codelines and Branching

Chapter 5
Resolving Conflicts

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" on page 69.

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:

Bruno opens //depot/dev/main/jam/command.c#8 for edit.
Gale subsequently opens the same file for edit in her own client workspace.
Bruno and Gale both edit //depot/dev/main/jam/command.c#8.
Bruno submits a changelist containing //depot/dev/main/jam/command.c, and the submit succeeds.
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.


Note	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" on page 58.

To resolve conflicts and submit your changes, perform the following steps:

Sync the files (for example p4 sync //depot/dev/main/jam/...). Perforce detects any conflicts and schedules the conflicting files for resolve.
Issue the p4 resolve command and resolve any conflicts. See "Options for resolving conflicts" on page 63 for details about resolve options.
Test the resulting files (for example, compile code and verify that it runs).

Submit the changelist containing the files.


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


File revision	Description
`yours`	The revision of the file in your client workspace, containing changes you made.
`theirs`	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`.)
`base`	The file revision in the depot that `yours` and theirs were edited from (the closest common ancestor file).
`merge`	The file generated by Perforce from `theirs`, `yours`, and `base`.
`result`	The final file resulting from the resolve process.

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 was changed identically in yours and 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:

Accept a file without changing it (see "Accepting yours, theirs, or merge" on page 64)
Edit the merge file with a text editor (see "Editing the merge file" on page 64)
Merge changes selectively using a merge program (see "Merging to resolve conflicts" on page 65)

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" on page 68.

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.


Option	Description	Remarks
`a`	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.
`ae`	Accept edit	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.
`am`	Accept `merge`	Accept `merge` into the client workspace as the resolved revision. The version in the client workspace is overwritten.
`at`	Accept `theirs`	Accept `theirs` into the client workspace as the resolved revision. The version in the client workspace is overwritten.
`ay`	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.


Option	Action	Remarks
`?`	Help	Display help for `p4 resolve`.
`a`	Accept automatically	Accept the autoselected 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.
`ae`	Accept edit	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.
`am`	Accept `merge`	Accept `merge` into the client workspace as the resolved revision. The version in the client workspace is overwritten.
`at`	Accept `theirs`	Accept `theirs` into the client workspace as the resolved revision. The version in the client workspace is overwritten.
`ay`	Accept `yours`	Accept `yours` into the client workspace as the resolved revision, ignoring changes that might have been made in `theirs`.
`d`	Diff	Show diffs between `merge` and `yours`.
`dm`	Diff `merge`	Show diffs between `merge` and `base`.
`dt`	Diff `theirs`	Show diffs between `theirs` and `base`.
`dy`	Diff `yours`	Show diffs between `yours` and `base`.
`e`	Edit merged	Edit the preliminary merge file generated by Perforce.
`et`	Edit `theirs`	Edit the revision in the depot that the client revision conflicts with (usually the head revision). This edit is read-only.
`ey`	Edit `yours`	Edit the revision of the file currently in the workspace.
`m`	Merge	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.
`s`	Skip	Skip this file and leave it scheduled for resolve.


Note	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" on page 58.

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

`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. <<<< \+/

`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" on page 69.

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.


Flag	Description
`-a`	Accept the autoselected file.
`-ay`	Accept `yours`.
`-at`	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.
`-am`	Accept the recommended file revision according to the following logic: 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, leaving it unresolved.
`-af`	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.
`-as`	Accept the recommended file revision according to the following logic: 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

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.


Command	Meaning
`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`	Diffs two depot files. The specified files can be any two file revisions and different files. 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]`	Previews the specified sync, listing which files have conflicts and need to be resolved.
`p4 resolved`	Reports files that have been resolved but not yet submitted.

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:

Bruno opens file for edit.
Gale opens the same file in her client for edit.
Bruno and Gale both edit their client workspace versions of the file.
Bruno submits a changelist containing that file, and his submit succeeds.
Gale submits a changelist with her version of the file; her submit fails because of file conflicts with the new depot's file.
Gale starts a resolve.
Bruno edits and submits a new version of the same file.
Gale finishes the resolve and attempts to submit; the submit fails and must now be merged with Bruno's latest file.

...and so on.

To prevent such problems, you can lock files, as follows.

Before scheduling a resolve, lock the file.
Sync the file (to schedule a resolve).
Resolve the file.
Submit the file.
Perforce automatically unlocks the file after successful changelist submission.

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.