mergelist

determine which versions need to be promoted between streams

Usage

accurev mergelist -s <from-stream> -S <to-stream> [ -o ] [ -d ]
[ -fl ] [ -fx ] { [ -Fx ] -l <list-file> | <element-list> }

Description

The mergelist command determines which element versions must be promoted from one stream (the “source” or “from” stream) to another stream (the “destination” or “to” stream) in order to fulfill this synchronization requirement: after the promotions, all changes recorded in the source stream will have been propagated to the destination stream.

Note: For some elements, a merge may be required before such a promotion can occur; for other elements, the version in the source stream can be promoted to the destination stream immediately, without requiring a merge first.

mergelist merely provides information. It does not perform any actual merge or promote commands. This command is the “engine” used by the GUI’s Send to Change Palette command to populate the Change Palette with a list of versions to be merged/promoted.

Typically, you invoke mergelist on two non-workspace streams. But the command works for any two streams. A case that’s particularly informative is determining which versions need to be promoted from a workspace stream to its own backing stream:

accurev mergelist -s gizmo_3.4_john -S gizmo_3.4

This command lists all the versions that are active in the workspace stream gizmo_3.4_john — that is, the members of the workspace stream’s default group. By definition, the default group records the set of workspace-stream versions that have not yet been promoted to the backing stream.

The ‘mergelist’ Algorithm

mergelist works on an element-by-element basis. For each element in the source stream, it considers the relationship between:

  • the real version associated with the version in the source stream
  • the real version associated with the version in the destination stream

This relationship determines whether the source-stream version will be added to the list of versions to be promoted to the destination stream.

Note: Non-workspace streams contain virtual versions of elements. Each virtual version is associated with (is a reference to) some real version of the element, which was created in some workspace stream.

Here are all the cases:

No version of the element exists in destination stream.

The source stream’s version is placed on the to-be-promoted list. No merge will be required.

The same real version appears in both in the source and destination streams.

No difference, so no promotion required.

The source-stream version was derived from the destination-stream version.

The source stream’s version is placed on the to-be-promoted list. No merge will be required.

The derivation can be either direct (a series of keep commands) or indirect (one or more merge commands, along with keep commands). Note that patch commands don’t count in this analysis of a version’s derivation.

The destination-stream version was derived from the source-stream version.

No promotion is required, because the content of the source-stream version is already present in the destination-stream version.

Neither version is derived from the other; both are derived from some common ancestor version.

The source stream’s version is placed on the to-be-promoted list. A merge will be required to combine the two versions’ changes from the common-ancestor version (and possibly resolve conflicts in those changes).

‘mergelist’ vs. ‘diff’

The mergelist command is quite similar to the form of the diff command that shows the differences between two streams:

accurev diff -a -i -v <stream-1> -V <stream-2> 

These commands differs only in how they handle elements for which “the destination-stream version was derived from the source-stream version”:

  • The mergelist command does not place such elements on the to-be-promoted list, because no promotion is required to get the changes into the destination stream. (The changes are already there.)
  • The diff command does report such elements, because the two streams do contain different versions of the element.

Options

-s <from-stream>

The stream to be searched for versions that need to be promoted.

-S <to-stream>

The stream that the versions need to be promoted to.

-o

Select only elements whose source-stream and destination-stream versions overlap, requiring a merge.

-d

Select only elements that are active in the “from” stream’s default group.

-fl

Display locations only (no status indicators or version-IDs).

-fx

Display the results in XML format. Use this option when there is a need to include version information for each element listed in the file.

-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:

	<elements>
    <e l="\.\file_0001" v="4/1" eid="2"></e>
    <e l="\.\file_0002" v="4/1"></e>
    <e eid="4" v="4/1"></e>
</elements>

Examples

Find all the versions that need to be promoted in order to propagate all the changes recorded in stream gizmo_4.3_maint to stream gizmo_test:

> accurev mergelist -s gizmo_4.3_maint -S gizmo_test

Considering only the elements listed in file /tmp/myfiles, find the versions that need to be promoted to incorporate stream ColorStar1.3.1’s changes into stream ColorStar2.0:

> accurev mergelist -s ColorStar1.3.1 -S ColorStar2.0 -l /tmp/myfiles

See Also

diff , merge, mergelist, patchlist, promote

Using a Specific Version of an Element