The Promote command sends one or more versions from one stream 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 and make them public by sending them to the workspace's backing stream.
Note: Promoting an element or symbolic link operates on the link itself, not on the target of the link.
Generally speaking, you use promote to share changes to elements that are already under AccuRev control. Note, however, that you can use the promote operation on external files -- when you promote a file with an (external) status, AccuRev automatically performs the actions required to place the file under AccuRev control.
The Promote command creates a virtual version in a dynamic stream. No data is copied from your machine to the repository by this command; it just creates new entries in the repository database. By contrast, the Keep command (as well as Anchor, Send to Workspace, Revert, Rename, Defunct, and the CLI-only command undefunct) creates a real version in a workspace stream. See Real Versions and Virtual Versions.
If an element has (overlap) status, you cannot promote it. You must merge your version with the version in the backing stream, to create a new, merged version. You can then promote the merged version. See Merging Your Changes with Someone Else's Changes for more information.
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 Basis command to 'undo' the changes in your workspace. In other cases, you can merge and promote, as with (overlap)-status elements.
Tip: Although you can promote files from the Explorer, Outgoing Changes, and Conflicts modes, consider using the Outgoing Changes mode to see all the new work and changes you might want to promote to the parent stream.
|
2.
|
Click the
 button in the Details pane toolbar, or right-click and choose Promote from the context menu. |
If AccuRev is integrated with an ITS, the Select Issue (Change Package) dialog box appears. Choose the issues against which you want to promote your changes and click Ok to continue. See Promoting Changes When AccuRev is Integrated with an ITS for more information.
|
3.
|
Optionally, enter a comment describing the changes you are promoting. (AccuRev "seeds" the text box with the most recent Promote comment made during your current AccuRev GUI session.) The comment string becomes a permanent annotation to the transaction that creates the new version(s) in the destination stream.
|
Tip: AccuRev itself does not require a comment, but your organization can establish such a requirement by putting a trigger on the Promote command.
|
4.
|
Optionally, clear the Promote checkbox for any versions that you do not want to promote.
|
|
5.
|
Click the Promote button.
|
The elements’ status changes to (backed). If you performed the promote operation from in Outgoing Changes mode, the element is removed from the Details pane.
You can select one or more of the issue records and click Ok; or you can type one or more numbers (SPACE-separated) in the Issue input field. When you promote, the integration(s) record information about the Promote transaction in the issue record(s) you designate.
Note: If you have enabled the use of third-party ITS keys in the AccuWork schema, the Select Issue (Change Package) dialog displays additional controls that let you specify whether you want to use AccuWork issue numbers or third-party keys when selecting issues to promote against. See Using Third-Party Keys in the AccuRev GUI for more information.
A dependent element is an element that has a relationship with another element. Dependent elements must be promoted as a group in order to resolve the dependency. This section describes how dependencies can be created and how to promote them.
A dependency can be created when you rename an element in the workspace using the name of another element that has also been renamed and promoted to the backing stream. For example, imagine that you add the following files to your workspace, and then keep them and promote them to the backing stream:
proposed_tracker.c is renamed as accepted_tracker.c
beta_tracker.c is renamed as proposed_tracker.c
ref_tracker.c is renamed as beta_tracker.c
beta_tracker.c is renamed as proposed_tracker.c
ref_tracker.c is renamed as beta_tracker.c
The element accepted_tracker.c can be promoted freely -- it has simply been renamed using a new name (that is, the name of an element that has not already been promoted to the backing stream). Notice, however, that elements beta_tracker.c and ref_tracker.c were renamed with names of elements that have already been promoted to the backing stream and now have dependencies (proposed_tracker.c and proposed_tracker.c, respectively), creating a dependency -- proposed_tracker.c cannot be promoted from the workspace without accepted_tracker.c. Similarly, beta_tracker.c requires that both proposed_tracker.c and accepted_tracker.c be promoted with it.
When AccuRev detects a dependency during a promote operation, it displays a message alerting you to the dependency and the requirement to promote dependent elements together, as a group.
When you dismiss the message, the Promote dialog box appears. Dependent elements are included in the table, along with any other files you have selected for promote, as shown in the following illustration:
Dependent elements are displayed with a warning icon in the Dependency column. Elements that share a dependency are highlighted using the same color. Because dependent elements must be promoted together, clearing the Promote check box for one element in a group clears the check box for all elements in that group.