Layout of the Specified Versions Pane
Columns in the Specified Versions Table
Layout of the Merged Versions Pane
Working in a Change Palette Tab
Specifying the Destination Stream
Sending Versions to the Destination Stream
Merging the Source and Destination Versions
Selecting a Workspace for Performing Merges
Patching Changes from the Source Version into the Destination Version
The Change Palette is a tool for propagating changes 'outside the lines' of a depot's stream hierarchy The tree-structured collection of streams -- including snapshots and workspace streams -- for a particular depot.. You use it to promote The operation (Promote command) that transitions a version from being active in one workspace or stream to being active in the parent stream (or some other stream). This operation creates a new virtual version in the parent stream; the virtual version provides an alias for the real version, which was originally created in some user's workspace. See version. one or more versions from a dynamic stream A stream whose configuration changes over time, with new versions promoted from child workspaces and/or from other dynamic streams. It also inherits versions from its parent stream. to a stream other than its parent stream (backing stream, basis stream) The stream that is just above a given workspace or stream in a depot's stream hierarchy. The given workspace/stream inherits versions from the parent stream.. In some cases, a merge An operation that combines the contents of two versions (contributors) of the same element. To merge the contents of text files, AccuRev uses a '3-way merge' algorithm: it compares the two files line-by-line with a third file, the version that is the closest common ancestor of the other two. Merging of namespace changes also takes into account the closest common ancestor. operation is required before you can propagate changes between streams; the Change Palette helps you to manage the Merge and subsequent Promote commands. You can use Patch instead of Merge, in order to send just some -- not all -- of the changes that a version contains.
You can also use the Change Palette to send changes from a dynamic stream to a workspace. This can be accomplished with a simple checkout An operation that makes a file active in a workspace, without recording any new changes to the file in the repository. In an exclusive file locking or anchor-required workspace, a checkout transitions the file from read-only to writable. operation, or with a more complex merge or patch A selected set changes (typically, the 'recent changes' made by one user) to a text-file element. Also, the merge-like operation that incorporates those changes in another version of the same element. See merge, basis version, head version, change package, reverse patch. operation.
You cannot use the Change Palette to promote versions from your workspace to an arbitrary stream. The only destination for versions in a workspace is the workspace’s backing stream, via the Promote command. (But you can reparent The operation that changes the parent stream of a particular workspace or stream. a workspace to provide a new destination for promoted versions.)
Before using the Change Palette itself, you must specify the version(s) that are to be promoted 'outside the lines' of the depot’s stream hierarchy. You can do this in the variety of contexts listed below. Click each summary description for a fuller description and an example.
From a Stream Browser ...
Selected items from a current development activity subwindow
The current development activity subwindow shows the development activity An element is said to be active in a workspace or stream if a new version of the element has been created there, and that version has not been either (1) promoted to the parent stream or (2) purged from the workspace or stream. See default group, backed, passive. An issue record is said to be active in a workspace or stream if the head version of one or more of its change package entries is in the stream's default group. currently taking place in a stream or workspace -- by element, by transaction, or by issue record. In this subwindow, you can:
Select any number of items (elements, transactions, or issue records).
Invoke the Send to Change Palette command, using the toolbar button or the selection's context menu.
All the versions with changes that have not been propagated to the destination
Instead of selecting individual versions, you can let AccuRev determine the complete set of versions in a source stream that have not yet been propagated to a destination stream or workspace.
This can include versions that are not currently in the source stream’s default group at all, but are inherited from a higher-level stream.
Click the control below the source stream, and drag it to the destination stream or workspace.
From the Details pane of a File Browser, opened on a stream ...
Selected versions from the default group
This is essentially the same as working in a Default Group subwindow in the Stream Browser:
Select the Default Group search.
Select any number of the stream's active versions.
Invoke the Send to Change Palette command, using the toolbar button or the selection's context menu.
From a History Browser or Active Transactions tab, opened on a stream ...
All the versions in specified transaction(s)
A History Browser tab shows all the transactions that created (via Promote) versions in a stream. An Active Transactions tab shows the subset of these transactions with at least one version still active in the stream. In either one, you can load a Change Palette with the versions created one or more selected transactions.
Select one or more transactions in the Summary (upper) pane.
Invoke the Send to Change Palette command, using the toolbar button or the selection's context menu.
Specified version(s) from one transaction
This is similar to the previous case: instead of loading a Change Palette with all the versions created in a transaction, you load selected versions from a transaction.
Select one transaction in the Summary (upper) pane.
Select any number of that transaction's versions in the Versions (lower) pane.
Invoke the Send to Change Palette command, using the toolbar button or the selection's context menu.
From a Stream Issues tab, opened on a stream ...
All the versions in the change package(s) of the specified issue record(s)
A Stream Issues tab shows the issue records whose change packages are "in" a particular stream. Each change package contains a "patch" of data from one or more text-file elements. You can load a Change Palette tab with the versions in one or more issue records' change packages:
Select one or more issue records in the Issues (upper) pane.
Invoke the Send to Change Palette command, using the toolbar button or the selection's context menu.
In all cases, a new Change Palette tab appears, loaded with the versions you've specified.
The Change Palette tab includes these panes:
The Specified Versions pane initially lists all the versions you specified with the Send to Change Palette command (or the drag-and-drop operation). The versions' entries are cleared from this pane as you work with them using Promote, Merge, Patch, etc.
The Merged Versions pane appears only after you've merged or patched versions in the Specified Versions pane. It lists the versions created by the Merge or Patch command, and provides a convenient way to Promote these versions to the destination stream.
This pane contains a table that initially lists all the versions loaded into the Change Palette.
As you work with these versions, they "migrate" out of this pane:
Entries for versions that you promote to a destination stream -- or send to a destination workspace -- are automatically cleared from the Change Palette.
Entries for versions that you Patch into a workspace (based on the source or destination stream) are also cleared automatically.
Entries for versions that you Merge into a workspace (based on the source or destination stream) are automatically cleared from the Specified Versions pane. Corresponding entries, representing the versions created by the Merge, are added to the Merged Versions pane.
The Specified Versions table includes these columns:
Element (or separate "Name" and "In Folder" columns)
The element's pathname within the depot.
Version
The version of the element that was sent to the Change Palette.
Basis Version
The version/basis-version pair defines the "patch data" that will be incorporated into the destination version if you invoke the Patch command. See Patches and Change Packages.
Transaction
(if you invoked Send to Change Palette from a History Browser or Active Transactions tab) The number of the transaction from which you sent this version.
The relationship between the version in the source stream and the version in the destination stream:
(overlap) indicates that you must perform a Merge command prior to Promote'ing this element to the destination stream. You can also perform a Patch command to propagate some of this version's changes to the destination stream, but this does not resolve the overlap Version X, in a workspace or stream, has 'overlap' status if the parent stream’s current version of the element contains changes that are not reflected in version X. Such a version cannot be promoted to the parent stream; the user must create a new version with a merge operation, combining version X with the parent stream’s version. The new, merged version can then be promoted. See deep overlap. status (and so does not enable the Promote command).
(patch) indicates that the change that you sent to the Change Palette for this element (as specified by its entries in the Version and Basis Version columns) is a patch. That is, the change does not include the entire set of changes between the source-stream version and the closest common ancestor of the source-stream and destination-stream versions. You can perform a Patch command to propagate the changes in the patch to the destination stream.
If the element does not also have (overlap) status, the Promote command is enabled for this version, too. But promoting would propagate more changes to the destination stream than were loaded into the Change Palette. AccuRev issues a warning if you invoke Promote on this version.
A blank indicates that there is no overlap and that the change loaded into the Change Palette is not a patch. This means you can safely Promote the version to the destination stream.
The Specified Versions pane also includes:
Source Stream
The name of the stream from which you sent the versions, using Send to Change Palette or the drag-and-drop operation.
Destination Stream
Initially blank (unless you used the drag-and-drop operation to load the Change Palette). Subsequently, it displays the name of the stream or workspace you've selected as the versions' destination.
Resolve overlaps in workspace
This field does not appear until the first time you invoke the Merge command. At that point, AccuRev prompts you to specify a workspace for the merge operation to take place in. It then displays the workspace's name in this field (which is also a listbox control for changing the name).
This pane contains a table that lists the versions you've created by invoking the Merge command on versions in the Specified Versions pane. As you proceed to Promote these newly created versions, their entries are cleared from the Change Palette.
The Merged Versions table includes these columns:
Element (or separate "Name" and "In Folder" columns)
The element's pathname within the depot.
Merged in Workspace
The name of the workspace in which the merged version was created. This is not necessarily the same for all the listed elements, since you can switch workspaces using the Resolve overlaps in workspace control.
The following sections describe the tasks you perform in a Change Palette tab. The order of the sections follows the typical order of tasks. But the Change Palette is a long-lived "work environment", not a simple dialog box or sequential wizard. So you might perform just some of the tasks and/or perform them in a different order.
Specifying the Destination Stream
Sending Versions to the Destination Stream
Merging the Source and Destination Versions
Selecting a Workspace for Performing Merges
Patching Changes from the Source Version into the Destination Version
Multiple Entries for the Same Element
If you've loaded versions into the Change Palette using the Send to Change Palette command, you've already indicated the source stream, but need to specify the destination stream or workspace. (The drag-and-drop operation indicates both the source and destination.)
Click the arrow control next to the Destination Stream field. A dialog appears, listing all of the depot's streams and workspaces. Select one to be the destination for subsequent commands on the versions in the Specified Versions pane. [example]
As the example shows, AccuRev determines a status for each element, describing the relationship between the source-stream version and the destination-stream version. [note ] Entries with (overlap) status are highlighted in yellow.
You can change the destination stream at any time, using the arrow control next to the Destination Stream field.
In the Specified Versions pane:
If the destination is a stream, you can immediately Promote the versions that do not have (overlap) status.
If the destination is a workspace, you can immediately Send to Workspace any or all versions, whether or not they have (overlap) status.
Select one or more eligible versions, then click the button in the pane's toolbar or choose Promote (or Send to Workspace) from the selection's context menu. When the command completes, the entry(s) for the version(s) are cleared from the Change Palette.
In the Merged Versions pane, you can Promote versions at any time. The versions are active in the workspace listed in the Merged in Workspace column; Promote sends them to this workspace's backing stream.
Notes (click to view):
If you've used multiple workspaces for merging ...
In each Promote invocation, the set of versions must all be in the same workspace.
If you've merged using a workspace based on the source stream ...
Promoting sends the merged version to the workspace's backing stream, which is not the destination stream you originally specified. You can now promote this version from the workspace's backing stream to the original destination stream (no additional merge is required). But you'll need to use another instance of the Change Palette to invoke the Promote command.
If an entry in the Specified Versions pane has (overlap) status, you cannot immediately promote the version to the destination stream. First, you must create a new version by merging the source and destination versions.
The merge operation must take place in a workspace that belongs to you and is based on either the source or destination stream. If you have not already selected a merge workspace, you must do so before performing any merges.
Select one or more versions with (overlap) status, and click the button in the pane's toolbar or choose Merge from the selection's context menu.
The merge operation(s) proceed for the selected element(s), as described in the Merge help topic. [note ]
A merged version cannot be created directly in either the source or destination stream, because these are dynamic streams A stream whose configuration changes over time, with new versions promoted from child workspaces and/or from other dynamic streams. It also inherits versions from its parent stream. — all new versions of AccuRev elements must be originally created in workspaces. The first time you invoke Merge in the Specified Versions pane, AccuRev prompts you to establish a merge workspace, suggesting one that is based on the destination stream. You can also choose a workspace based on the source stream.
Notes (click to view):
Which is preferable -- source or destination?
A workspace based on the destination stream is preferable. After you perform the merge, you can then accomplish the original task -- propagating a version's changes to the destination stream -- with a single Promote. If you use a workspace based on the source stream, you'll need to Promote twice: (1) from the merge workspace to the source stream; (2) from the source stream to the destination stream. The second one requires you to use another instance of the Change Palette.
What if no candidate workspace exists?
Click Cancel in the choose-workspace dialog, and do either of the following:
Create a workspace based on one of the streams.
Reparent one of your existing workspaces to the source or destination stream. Be sure to Update the reparented workspace before using it to perform merges in the Change Palette.
After you select a merge workspace, its name is displayed at the bottom of the Specified Versions pane. You can change this setting at any time; this enables you to use different workspaces to merge different versions.
If a entry in the Specified Versions pane has (patch) status, you can invoke the Patch command to incorporate the patch defined by the Version and Basis Version settings into the destination-stream version. Select one or more of these versions, and click the button in the pane's toolbar or choose Patch from the selection's context menu. AccuRev prompts you to select a workspace that belongs to you and is based on the destination stream. The patch operation is performed in this workspace, as described in the Patch help topic.
When the patch operation is complete, the entry disappears from the Specified Versions pane.
In some cases, the Specified Versions pane of the Change Palette can get populated with multiple entries for the same element. Here is a simple scenario:
Successive changes to an element, brass.c, get assigned to different AccuWork issue records. For example, this illustration shows a two-version change assigned to issue #14, then a one-version change assigned to issue #7, then a two-version change assigned to issue #22.
At this point, all three issues (#14, #7, and #22) are "in" the stream to which the versions were promoted.
Open a Stream Issues window for the stream to which the versions were promoted, then select issues #14 and #22 and invoke the Send to Change Palette command. Since there is a "change package gap", consisting of version 33, between the two change package entries for brass.c, AccuRev cannot combine them into a single patch entry. Accordingly, the two entries are entered into the Change Palette separately:
The total number of entries for a given element is displayed in the Count column. The (patch) indicators in the Status column indicate that Patch is the appropriate command to invoke on each entry, in order to propagate the changes to brass.c in issue records #14 and #22 (and no other changes) to the destination stream.
Clear
Remove the selected entry(s). You can clear entries from either pane. This capability helps you to keep track of your work (and the work that you've decided not to do).
If you attempt to close the Change Palette tab when either pane in non-empty, AccuRev prompts you for confirmation.
Promote
(available only if the destination is a dynamic stream)
Specified Versions pane: promote the selected version(s) to the destination stream.
Merged Versions pane: promote the selected version(s) from the workspace listed in the Merged in Workspace column to its backing stream.
Send to Workspace
(available only if the destination is a workspace) Performs a Send to Workspace command on the selected version(s) in the destination workspace.
Merge
Merge the selected version(s) with the corresponding version(s) in the destination stream, creating the merged version(s) in the workspace listed in the Resolve overlaps in workspace field. When the command finishes, the entry(s) are cleared from the Specified Versions pane, and entry(s) for the newly created version(s) are added to the Merged Versions pane.
Patch
Performs a Patch command from each selected version to the corresponding version in the destination workspace, or in a workspace that you select below the destination stream. When the command finishes, the entry(s) are cleared from the Specified Versions pane.
Browse Versions
Open a Version Browser tab, showing all the versions of the selected element, and their interrelationships (ancestry).
Diff
Compares the selected version with the version in the destination stream or workspace. [note ]
Properties
Displays information about the selected element. The data items displayed vary with the type of element.