Resolve conflicts

In settings where multiple users are working on the same set of files, conflicts can occur. Helix 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, Helix requires you to resolve the conflict.

Merging changes from a development stream to a release stream is another typical task that requires you to resolve files.

To prevent conflicts, Helix 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, see Locking files.

How conflicts occur

Conflicts can occur in a number of ways, for example:

  1. Bruno opens //JamCode/dev/jam/command.c#8 for edit.
  2. Gale subsequently opens the same file for edit in her own client workspace.
  3. Bruno and Gale both edit //Jamcode/dev/jam/command.c#8.
  4. Bruno submits a changelist containing //JamCode/dev/jam/command.c, and the submit succeeds.
  5. Gale submits a changelist with her version of //Acme/dev/jam/command.c. Her submit fails.

If Helix accepts Gale’s version into the depot, her changes will overwrite Bruno’s changes. To prevent Bruno’s changes from being lost, Helix 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. Helix 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, Helix requires you to resolve to prevent your own changes from being overwritten by the depot file.

By default, Helix uses its diff program to detect conflicts. You can configure a third-party diff program. For details, see Diff files.

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

  1. Sync the files (for example p4 sync //Acme/dev/jam/...). Helix 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. Test the resulting files (for example, compile code and verify that it runs).
  4. 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 Helix 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: 

C:\bruno_ws> p4 resolve //Acme/dev/jam/command.c
c:\bruno_ws\dev\main\jam\command.c - merging //Acme/dev/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.

Helix’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 options. To re-resolve a resolved but unsubmitted file, specify the -f option when you issue the p4 resolve command. You cannot re-resolve 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. Helix 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 ae.

By default, only the conflicts between the yours and theirs files are marked. To generate difference markers for all differences, specify the -v option 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 auto-selected 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 Helix.

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 Helix server, but the differences displayed by dy, dt, dm, and d are generated by your computer’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 Diff files.

Example 26. Resolving file conflicts

To resolve conflicts between his work on a Jam README file and Gale’s work on the same file, Bruno types p4 resolve //Acme/dev/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 he and Gale 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 Gale 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.

Resolving branched files, deletions, moves and filetype changes

Beyond reconciling changes to the contents of related files after integration, you can also determine how other kinds of changes are handled. Consider this example:

  • You edit header.cc in the mainline while a coworker deletes it in the release branch (or vice versa). You integrate fixes in the release branch back to main. During resolve, you can decide whether header.cc is deleted from the mainline or the action in the release branch is ignored, preserving header.cc in the mainline.
  • A developer implements RCS keywords in source files in a development branch, and changes their Helix filetype from text to text+k. The release manager wants to integrate new features from the development branch to the mainline, but does not want to enable keyword expansion in the mainline. During resolve, the release manager can choose to ignore the filetype change.
  • The file header.cc is branched from main to rel. Subsequently, it’s renamed to headerx.cc in main, and moved in the release branch to the headers subfolder.

Following are simple cases describing how you can resolve non-content changes to related files. After a source file is branched to a target file, changes are made as describe below, then you integrate the source to the target. To choose the outcome, you specify the resolve options at (“Accept Theirs”) or ay (“Accept Yours”) as follows:

  • The source is edited and target is deleted: the at option re-adds the source in the target branch. The ay option causes the file to remain deleted in the target branch.
  • The source is deleted and the target is edited: the at option causes the file to be deleted in the target branch. The ay option retains the edited content in the target branch.
  • The target file was moved after being branched: the at option moves the target file to the source file name and location. The ay option retains the target file name and location.
  • The filetype of the source file was changed after it was branched: the at option propagates the change to the target. The ay option leaves the filetype of the target unchanged. If the differing filetypes do not conflict, you have the option of combining them.

  • Files have been moved or renamed in conflicting ways: you are prompted to choose a path and filename. Example: 

    Resolving move to //Acme/rel/headerx.cc
Filename resolve:
at: //Acme/rel/headerx.cc
ay: //Acme/rel/headers/header.cc
am: //Acme/rel/headers/headerx.cc

By default, the p4 resolve command resolves all types of change, content and non-content. To constrain the type of actions that you want to resolve, specify the -A option as follows:

Option What is Resolved

-Aa

Resolve attributes set by p4 attribute.

-Ab

Integrations where the source is edited and the target is deleted.

-Ac

Resolve file content changes as well as actions.

-Ad

Integrations where the source is deleted and target is edited.

-Am

Renames and moves.

-At

Filetype changes.

-AQ

Charset changes.

To perform more than one type of resolve, combine the options (for example: -Abd). By default, resolving is performed file by file, interactively. To specify the same outcome for a particular action (for example, propagate all moves), and avoid the prompting, include the desired option on the command line. For example: p4 resolve -Am -at

Resolve command-line options

The p4 resolve options described below enable you to resolve directly instead of interactively. When you specify one of these options in the p4 resolve command, files are resolved as described in the following table:

Option Description

-a

Accept the auto-selected 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 27. 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, Helix 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.