The Promote Command
The Promote command sends one or more versions A particular revision of an element, reflecting a content change (files only) or a namespace change (files and directories). All versions are originally created in workspaces, and can subsequently be promoted to dynamic streams. The original (workspace) version is termed a 'real version'. Each promotion to a dynamic stream creates a 'virtual version', which serves as an alias for (pointer to) the original real version. from one stream The AccuRev data structure that implements a configuration of the elements in a particular depot. The configuration of a dynamic stream changes over time; the configuration of a snapshot (static stream) never changes. Each workspace has its own private workspace stream. See workspace, stream hierarchy. to another, making the versions accessible in the destination stream -- and in workspaces and streams below it. A single transaction in the AccuRev depot records the creation of the new version(s) in the destination stream.
The basic use of Promote is to take the private versions that you've created in your workspace stream The private stream that is built into a workspace. All new versions of elements are originally created in workspaces; AccuRev records these versions in workspace streams. and make them public by sending them to the workspace's backing stream (parent 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 backing stream..
Promote can also send versions from a dynamic stream to any other dynamic stream. You can such higher-level promotion using the File Browser or Stream Browser tool. Promoting from a stream to a non-parent ("cross-promotion") requires use of an additional tool, the Change Palette.
Notes (click to view):
Real versions and virtual versions
The Promote command creates a virtual version A version of an element, created in a dynamic stream as an alias for (reference to) a previously created real version. in 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.. By contrast, the Keep command (and several others ) creates a real version A version of an element, created in some user’s workspace, recording a change to the contents and/or pathname of the element. See version, virtual version. in a workspace stream The private stream that is built into a workspace. All new versions of elements are originally created in workspaces; AccuRev records these versions in workspace streams.. See Real Versions and Virtual Versions.
Inheritance of promoted versions
After you promote a version, it can be inherited by all 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. and workspaces A location in which one or more users perform their work, using files under version control. Each workspace consists of a workspace stream in the repository, and a workspace tree in the user’s disk storage. below the backing stream ('parent 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 backing stream.. Inheritance by dynamic streams is automatic; inheritance by a workspace occurs when the user Update's it.
If an element has (overlap) status, you cannot promote it. You must merge An operation that combines the contents of two text files (contributors), which are versions of the same file element. 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. your version with the version in the backing stream ('parent 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 backing stream., to create a new, merged version. You can then promote the merged version.
The status (underlap) is similar to (overlap), in that an element has changed in your workspace and also in the backing stream. With (underlap), the changes in your workspace version have already been promoted to the backing stream (from another workspace, or from a stream elsewhere in the depot’s stream hierarchy). In many cases, it is most appropriate to use the Revert to Backed command to 'undo' the changes in your workspace. In other cases, you can 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. and 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., as with (overlap)-status elements.
You can promote versions in several contexts:
Select one or more elements in the Details pane of the File Browser. Then, click the button in the Details pane toolbar, or choose Promote from the selection's context menu. This promotes the versions to the backing stream.
Stream Browser (graphical display only)
Drag-and-drop the icon below a workspace to the backing stream, to promote all the versions currently in that default group The set of elements that are currently active in a particular workspace or stream..
Drag-and-drop the icon below a dynamic stream to its parent stream to perform a standard promotion
Drag-and-drop the icon below a dynamic stream to any other dynamic stream to initiate a cross-promotion. The versions are loaded into the Change Palette, where you complete the promotion (perhaps after performing some merges An operation that combines the contents of two text files (contributors), which are versions of the same file element. 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.).
Stream Browser: Default Group subwindow
In the graphical display, click the icon below a workspace or stream to open a subwindow displaying the versions currently in the default group The set of elements that are currently active in a particular workspace or stream. of that workspace or stream. Select one or more versions, then:
Click the button in the subwindow toolbar (or choose Promote from the selection's context menu) to promote the versions to the backing stream.
Click the button in the subwindow toolbar (or choose Send to Change Palette from the selection's context menu) to load the versions into the Change Palette where you complete the promotion (perhaps after performing some merges An operation that combines the contents of two text files (contributors), which are versions of the same file element. 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.).
The Promote dialog provides these command options:
Comment
You can enter a comment string in the text box. (AccuRev "seeds" the text box with your most recent Promote comment.) The comment string becomes a permanent annotation to the transaction that creates the new version(s) in the destination stream.
AccuRev itself does not require a comment, but your organization can establish such a requirement by putting a trigger The AccuRev facility that enables user-defined procedures (trigger scripts) to be performed automatically before or after certain operations take place. on the Keep command.
Promote (element list)
(only for direct-promotions to the parent stream -- not for cross-promotions) All the versions you specified are listed in a table. You can deselect individual versions by clearing the checkbox in the table's Promote column. Deselected versions will not be promoted.