Demote: Moving Elements Out of a Stream

The Demote command moves one or more element versions out of a parent stream (the source stream), while making those versions accessible in a child stream (the destination stream) — and in workspaces and streams below it.

Demote Overview

The basic use of demote is to stop sharing changes in a given stream by moving those changes out of the stream. A demote operation is different from a Revert to Basis operation in that the changes are not completely abandoned. Instead, the current file versions are retained in the child stream that you specify during the demote process.

Suppose, for example, you made some changes to the matrix.ini file and promoted your changes to the Dev stream, with the result that your changes were causing software builds to fail. You could demote those changes from the Dev stream to a child stream, which would enable your builds to succeed while you fixed the problematic file in another location. Once you had made the appropriate corrections, you could promote the matrix.ini file to the Dev stream once more.

The Demote option is available in several places in the AccuRev GUI, such as the StreamBrowser and in the Conflict mode of the Stream View Explorer.

When considering a demote operation, keep the following points in mind:

The destination stream must be an immediate child of the source stream. You cannot demote to a non-child stream nor can you demote more than one level beneath the source stream.
You cannot demote from a workspace, since it has no valid destination streams beneath it.
You can only demote the head version of an element.
You cannot demote elements that have dependencies or that have an overlap status in the destination stream.
A demote operation does not overwrite the element version in the destination stream if that version is newer than the version contained in the source stream.
Just as you can promote by file, transaction, or issue, you can also demote by file, transaction, and issue.
AccuRev recommends demoting by transaction as a best practice, since you can retain previous versions of the element in the source stream which you cannot do when demoting by file.

Demote and Entity Types

The following table indicates whether it is possible to demote to or from various AccuRev entities.

AccuRev Entity	Demote from?	Demote to?
Dynamic stream	Yes	Yes
Time-based stream	Yes	Yes
Snapshot stream	No	No
Pass-through stream	No	No
Gated stream	No	No
Workspace	No	Yes
Depot (root)	Yes	No
Reference tree	No	No

Demote by Transaction

Rather than demoting individual files, you can also demote a set of element versions by demoting a transaction. When you demote by transaction, the specific versions of the files in that transaction are no longer available in the source stream but they are now accessible in the destination stream.

The process of demoting by transaction enables you to leave previous versions of demoted elements active in the source stream. You cannot do this when demoting by file.

For example, suppose that you make three successive changes to a file and promote it after each change. If the file is problematic, demoting it by file means that the source stream now contains the version of the file that is in the backing stream. If, instead, you demote by transaction, you can demote the most recent transaction which leaves the previous version of the file active in the source stream.

The ability to demote a single transaction while leaving previous transactions in the source stream means that you can exercise a finer granularity of control over the intermediary versions of a file contained in the source stream than when demoting by file. For this reason, AccuRev recommends demoting by transaction as a best practice.

How to Demote by Transaction

To demote a transaction:

In the StreamBrowser, specify Active Transactions as the Active Group Mode.
Click the Show Active Transactions button to the right of the source stream.

Alternative: Right-click the source stream and choose Show Active Transactions from the context menu.

AccuRev displays a list of transactions:
To demote a transaction, select the transaction (say, for example, #65) and click Demote.

Note: You can demote multiple transactions at once, but the transactions you demote must be consecutive for an element and they must contain the most recent transaction. If, for example, you attempted to demote just transaction #63, AccuRev displays the following warning:
If the current stream has more than one child stream or workspace, AccuRev displays a dialog box that lets you choose the destination for the demote. Select the destination stream or workspace and click OK.

Note: If you attempt to demote from a stream that does not have a child stream or workspace, AccuRev displays the following warning:

When the demote operation has succeeded, transaction #65 and the file versions it contains have been moved out of the source stream (in this case, the Dev stream) and into the destination stream.

Demote by File

When you demote a file, you move it out of the default group of active files in the source stream and you move all active versions of it to a child stream (the destination stream) where it is added to that stream’s default group if there is no newer version of the file.

Note that after demoting a file, the source stream inherits the version of the file from its backing stream. Consequently, other versions of the file are no longer present in the source stream, although they exist in the destination stream.

How to Demote by File

To demote a version by file:

In the StreamBrowser, specify Active Files as the Active Group Mode and select the elements you want to demote.
Click the Demote button () on the StreamBrowser toolbar.

Alternative: Right-click and choose Demote from the context menu.

If the current stream has more than one child stream or workspace, AccuRev displays the Choose a destination stream for the demote dialog box:

Select the destination stream or workspace and click OK.

Note: The dialog box displays only those workspaces belonging to the current user.

The Demote dialog box appears.
In the Comment field, optionally enter a reason for the demote operation.

Tip: AccuRev retains the comment you entered from your most recent demote.

If there are any files listed that you do not wish to demote at this time, clear that file’s Demote checkbox.
Click the Demote button.

The version is no longer in the source stream but it is now active in the destination stream.

Demote by Issue