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:

keep

Overwrite the to version (the file in your workspace) with the current contents of the merged file; then keep a new version of the element in your workspace stream. If you haven’t edited the merged file, it may include conflict sections with separator lines, as shown above.

edit

Open a text editor on the merged file. Edit the conflict sections to resolve the conflicts and remove the separator lines.

merge

Discard the current contents of the merged file and restart the merge process on this file.

over

Replace the contents of the merged file with the contents of the to version (the file in your workspace). This is an override, declaring that you prefer your own version to the version in the backing stream.

diff

Compare the current contents of the merged file with the to version (the file in your workspace).

diffb

Compare the current contents of the merged file with the from version (the version in the backing stream).

skip

Cancel the merge for this file, and proceed to the next file specified on the command line (if any).

abort

Cancel the merge for this file, and end the merge command immediately.

help

Display short descriptions of these choices.

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

-B

(implies -i) Considering the entire backing chain of the workspace’s version, list each version that requires a merge with its parent version. This is similar to stat -B, but lists only the versions with overlap status.

-i

Display information about merge requirements, but don’t actually merge.

-G

Use AccuRev’s graphical Merge tool to perform the merge if there are conflicts which require human interaction (any value set in AC_MERGE_CLI is ignored).

-K

If an overlap with the backing-stream version does not involve any conflicts (and thus, no human intervention is required for the merge), perform the merge and keep the new version without asking for confirmation.

-o

Merge all files that need merging (files with (overlap) status).

-O

For each file to be merged, use the workspace version — as if you had selected over when merge prompted you to specify a merge action.

-I <issue-number>

Merge the contents of the change package of the specified AccuWork issue record. That is: for each change package entry indicated by an element argument, merge the entry’s head version with your workspace version.

-3

Specifies that the <issue-number> specified by the -I switch is a third-party ITS key rather than an AccuWork issue number.

--use_time_basis_for_overlap

Use the workspace's update level or the stream's time basis to identify overlap instead of using the current time.

When resolving overlap with a backing stream, this option causes AccuRev to merge against the version that was active in the backing stream at the time specified by the workspace's update level or the stream's time basis.

This option has no effect if the user uses the -v or -I option to merge against a specific version.

-v <ver-spec>

Merge to your workspace from the specified version or stream, instead of from the workspace’s backing stream. You cannot use -v and -s together.

-s <stream>

Uses your workspace to handle overlaps between the specified stream and its parent stream. That is, merge behaves as if <stream> were your workspace stream. (And this makes sense only if <stream> and your workspace stream both contain the same version of the file.) You cannot use -v and -s together. If you use this option, you must specify elements using depot-relative pathnames.

As with all merges, the results are placed in your workspace: keep’ing the results creates a version in your workspace stream, not in the <stream> you specified.

You can use a series of promote’s to propagate the merge results to the parent of <stream>.

-l <list-file>

Process the elements listed in <list-file>. This must be a text file, with one element name per line. Extra whitespace is not allowed; make sure there are no empty lines and no leading or trailing white space around the filenames. Wildcards are not expanded. There is no provision for comment lines in the file.

If you use this option, any <element-list> specified is silently ignored.

<element-list>

One or more element names, separated by whitespace. If you also specify a <list-file> using the –l option, this <element-list> is silently ignored.

-Fx

Signals that <list-file> (see the -l option) is an XML-format file, not a flat text file. Example:

  <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