merge

merge changes from another stream into the current version of an element

Usage

accurev merge [ -v <ver-spec> ] [ -G ] [ -K ] [ -O ][--use_time_basis_for_overlap]{ [ -Fx ] -l <list-file> | <element-list>}

accurev merge -o [ -G ] [ -K ] [ -O ][--use_time_basis_for_overlap]

accurev merge -i [ -B ] [ -v <ver-spec> | -s <stream> ][--use_time_basis_for_overlap]{ [ -Fx ] -l <list-file> | <element-list>}

accurev merge -io [ -B ] [ -v <ver-spec> | -s <stream> ][--use_time_basis_for_overlap]

accurev merge [-I <issue-number> [-3] ][--use_time_basis_for_overlap]{ [ -Fx ] -l <list-file> | <element-list> }

Description

The merge command edits your workspace’s copy of an element by combining its contents with the contents of the version currently in the backing stream. This command can also change the name of the element, if its name in the backing stream differs from its name in your workspace. These two kinds of changes are termed content changes and namespace changes, respectively.

You can specify multiple elements on the command line; each one will be merged as described above.

Variations: you can use the -v option to specify another stream’s version (instead of the backing stream’s version) as the from version; and you can use the -s option to merge to a stream other than your workspace stream.

Merge Input

AccuRev uses a 3-way merge algorithm: it considers the from and to versions, along with a third version: the closest common ancestor of these two versions. It determines this common ancestor by analyzing the stream hierarchy and taking into account previous merges for the element. (It does not take into account any patch commands you may have executed to incorporate other people’s changes into your version.) Thus, if you perform frequent merges on a file, you need to merge only the changes that have occurred since the last merge. You don’t have to consider all the changes back to the point at which the two versions diverged.

Performing the Merge

merge reports the three versions being considered, reporting each one in stream-number/version-number format:

Current element: /./chap01.doc
most recent ws version: 3/2, merging from: 4/2
common ancestor: 3/1

Then, it reports whether a merge of namespace changes is required ...

Namespace merge will be required

... and whether a merge of content changes is required ...

Automatic merge of contents successful. No merge conflicts in contents.
   or
** merge conflicts in contents, edit needed **

Performing the Namespace Merge. If a namespace merge is required, merge prompts you to choose one of the names:

Resolve name conflict by choosing name from:

(1) common ancestor: \.\ch01.doc

(2) backing stream : \.\chapter1.doc

(3) your workspace : \.\chap01.doc

Actions: (1-3) (s)kip (a)bort (h)elp

As the above example illustrates, a namespace merge is required if you have changed the element’s name in your workspace and the backing stream version also reflects a name change.

Performing the Content Merge. If a content merge is required, merge creates a temporary “merged file”, containing:

• All the changes between the common ancestor and the to version (the file in your workspace).
• All the changes between the common ancestor and the from version (the backing-stream version).

Non-conflicting changes are automatically inserted into the merged file. A change is non-conflicting if one of the contributors — either the “from” version or the “to” version — changed the content at that point in the file, but the other contributor didn’t make a change. (If exactly the same change was made in both contributors, that’s non-conflicting, too.)

A conflicting change occurs where both contributors contain a changes from the common ancestor. In this case, merge inserts both the “from” and “to” text sections into the merged file, along with separator lines:

<<<<<<< Your_Version                     (separator: start of conflict section)
text in "to" version"
text in "to" version"
text in "to" version"
====                                     (separator)
text at same location in "from" version"
text at same location in "from" version"
>>>>>>> Backing_Version                  (separator: end of conflict section)

After creating the merged file, merge asks what you want to do next:

Actions: keep, edit, merge, over, diff, diffb, skip, abort, help

action ?

The choices are:

If there are conflicts to be resolved, the default is to edit the merged file. If there are no conflicts, the merge is complete, and the default is to keep the merged file.

Choosing to edit the merged file launches a text editor. To resolve the conflicts:

1. Search for the separator lines.
2. n each conflict section, choose the change you would like, combine the changes, or edit the file however you would like.
3. Make sure to remove all the separator lines that mark the conflict section.

After you end the edit session, merge prompts you again to take an action. This time, “keep” is the default.

Merging Binary Files

There are no commonly accepted algorithms for merging binary files. Thus, if an overlap occurs in a binary-format element, there are only two ways to resolve the overlap:

• Use the copy in your workspace. Execute a merge command, and choose to keep the result. This keeps the copy in your workspace, and records a merge from the backing-stream version to your newly-kept version.
• Use the backing stream version. Execute a purge command. This resolves the overlap by removing the element from your workspace stream. Your workspace reverts to having a copy of the backing stream’s version of the element.

Determining Which Elements Need Merging

Use the stat -o command to list the elements that need to be merged before you can promote them to the backing stream. This lists all the elements whose changes in your workspace overlap changes in the backing stream.

Using Merges to Implement a Partial Update of Your Workspace

The update command performs its work on all the elements in your workspace. Sometimes, however, you may want to update just a selected set of elements to the versions currently in the backing stream. You can use a series of merge commands to do so. For example, if your backing stream is named gizmo_dvt and you want to update elements foo.c, bar.c, and read.me, this set of commands accomplishes the “partial update”:

accurev merge -v gizmo_dvt foo.c
accurev merge -v gizmo_dvt bar.c
accurev merge -v gizmo_dvt read.me

(You’ll probably want to use a script or a loop-processing command to make this task user-friendly.)

User Preferences

AC_MERGE_CLI: An environment variable used by merge to invoke an alternative merge program. (The default merge program is acdiff3 in the AccuRev bin directory.) The command string must specify all four files involved in the merge, using these substitution patterns:

%a% or %a — Filename of the common ancestor version.

%1% or %1 — Filename of the version in the backing stream (or other non-workspace version).

%2% or %2 — Filename of the version in the workspace.

%3% or %3 — Title to be displayed for the common ancestor version.

%4% or %4 — Title to be displayed for the version in the backing stream (or other non-workspace version).

%5% or %5 — Title to be displayed for the version in the workspace.

%o% or %o — Merge results (output) file.

The values that AccuRev substitutes for the %3%, %4%, and %5% patterns are not enclosed in double-quotes, even though the values typically include SPACE characters. The values that AccuRev substitutes for the other patterns are enclosed in double-quotes.

Make sure that the merge program you specify is on your search path. The program’s exit status should be:

Zero if there are no conflicting changes. The merge command’s default “do next” action after running this program will be keep.

Non-zero if there are conflicting changes. The merge command’s default “do next” action after running this program will be edit.

Options

  <workspace eolType="1"/>
  <element
    type="2"             # 1-directory, 2-text, 3-binary, 4-ptext, 5-element link, or 6-symbolic link
    option1="3"          # parent directory - see below for values
    option2="1"          # parent eid
    option3="3"          # element name - see note below for values
    option4="\.\cc.txt"  # backing name
    option5="\.\c"       # ancestor name
    option6="14"         # eid of element you are merging
    option7="C:\DOCUME~1\rtitle\LOCALS~1\Temp\merge60341.tmp"> # temp file 
    option8="3"          # link target - see below for values
  </element> 

Options 1, 3, and 8 (which specify how to resolve merge conflicts) can have the following values:

• >1 - Use information from the common ancestor>
• >2 - Use information from the backing stream>
• 3 - Use information from the workspace>

Examples

Merge in the changes to file foo.c from the backing stream:

> accurev merge foo.c

Merge in the changes to file foo.c from the maintenance stream:

> accurev merge -v gizmo_maint foo.c

Specify an alternative merge program:

> export AC_MERGE_CLI="fmerge %a %1 %2 %o"     (UNIX Bourne shell)

> set AC_MERGE_CLI="fmerge %a %1 %2 %o"        (Windows)

Extended Example

Assume the contents of the three versions are as follows:

• Common ancestor version — the version that both the backing-stream version and your workspace’s version are derived from:

  int
  main( int, char ** )
  {
      int a;
      a = 1;
      printf ( "a is %d\n" );
  }

• Backing stream version:

  int
  main( int, char ** )
  {
      unsigned int;
      a = 2;
      printf ( "a is %d\n" );
  }

• Copy in your workspace:

  int
  main( int, char ** )
  {
      long int;
      a = 1;
      printf ( "The value of a is %d\n" );
  }

Resolving Conflicts

The merge will automatically apply both of the non-conflicting changes, the one from the backing version and the one from your version. However, the conflicting change will be flagged and you will need to select the change that you want to preserve:

Merged Version

int
main( int, char ** )
{
<<<<<"fmerge %%a %%1 %%2"
    long int;
=====
    unsigned int;
>>>>>
    a = 2;
    printf ( "The value of a is %d\n" );
}

To select the change that you want, simply remove the change bars and the change that you don't want.

After saving the results of your changes, select the keep option from the menu to keep the changes and save a record of the merge. If you merged elements against the backing stream in order to be able to promote your changes, you can now promote the merged elements.

See Also

diff , keep, mergelist, patch, patchlist, stat

Using a Specific Version of an Element