demote

move a version from one stream to a child stream

Usage

accurev demote [ -c <comment> ] [ -d ] 
	[ -S <to-stream> ] ] 
	[ -I <issue-number(s)> [-3] ]
	{ -l <list-file> | <element-list> | -t <transaction-number> | -e <eid> 
	| -Fx -l <XML-file> }

Description

The demote command transitions a version from being active in the parent stream to being active in a child stream or workspace. The most common use of demote is to back out unwanted changes from a given stream yet still retain the changes in a child stream.

You can demote by file, by issue, and by transaction.

Note: You cannot demote to a destination that has active changes that overlap with the element you are demoting.

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

Staging stream

Yes

No

Workspace

No

Yes

Depot (root)

Yes

No

Reference tree

No

No

Note: While you cannot demote an element to or from a pass-through stream, you can demote an element across a pass-through stream that exists between the parent stream and a child stream or workspace.

Demote-Related Triggers

You can use the following AccuRev triggers with the demote command:

The server_preop_trig trigger fires on the server machine before the demote operation takes place, if the trigger has been configured for the depot in which the elements to be demoted reside. You can add a demote command section to this trigger to perform operations on the server before the demote occurs.

The pre-demote-trig trigger fires on the client machine before the demote operation takes place. You can use this trigger to perform actions on the client before the demote, such as cancelling the demote based on the user’s identity or privileges.

You can execute the event-stream trigger on the server after the demote operation completes. This trigger fires when a demote occurs in the parent stream of an event stream. You can use this trigger to perform actions based upon the demote operation, such as automatically starting a build after the demote has taken place.

For more information on triggers, see AccuRev Triggers in the AccuRev Admin Guide.

Demote and the Default Group

When you demote an element from a parent stream to a child stream or workspace, the element is removed from the default group of the parent stream, and is added to the default group of the child stream. That is, the element becomes inactive in the parent stream, and active in the child stream.

Options

–c <comment>

Specifies a comment for the transaction. The next command-line argument should be a quoted string. Alternatively, the next argument can be in the form @<comment-file>, which uses the contents of text-file <comment-file> as the comment.

-d

Selects all elements in the default group.

-e <eid>

Operates on the element with the specified element-ID. This is useful for demoting stranded elements from the backing stream. If you also specify a <list-file>, <element-list>, or <transaction-number>, it is ignored.

Tip: Use stat -i to list stranded elements.

-I <issue-number(s)>

You can specify the issue records to be demoted as a SPACE-separated list, enclosed in quotes:

-I "645 773 812"

-3

Specifies that any <issue-number> specified by the -I switch is a third-party ITS key rather than an AccuWork issue number.

-S <to-stream>

Demotes to the specified stream or workspace. The <to-stream> cannot be a snapshot stream, a pass-through stream, a gated stream, or the root of a depot.

-Fx -l <XML-file>

Identifies an XML-format text file that specifies one or more transactions, issue records, or elements you want to demote.

  • Example of XML format for transactions:

    <transactions>

          <id>71</id>

          <id>72</id>

          <id>73</id>

    </transactions>

  • Example of XML format for issues:

    <issues>
          <id>7</id>
          <id>21</id>
          <id>144</id>
    </issues>

    When specifying issues, you can use an optional third_party attribute if you have configured AccuRev to use an ITS other than AccuWork, as in the following example: 

    <issues third_party="true">
          <id>US23432</id>
          <id>DE726</id>
    </issues>

    If the third_party attribute is missing or set to “false”, AccuRev assumes that the <id> tag content is the AccuWork issue ID. All <id> tags must contain the same type of id, either AccuWork or third_party. You cannot mix id types in a single input XML file.

  • Example of XML format for elements:

    <elements>

          <e eid="2" location="/./file_1"/>

          <e eid="3"/>

          <e eid="6" location="/./a/b/file_2"/>

    </elements>

    The attributes allowed for elements are:

    • eid = the element id
    • location = the depot relative location of the element (this attribute is optional)

-l <list-file>

Processes 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 element names. Wildcards are not expanded. You cannot enter comment lines in a <list-file>.

<element-list>

Processes one or more element names, separated by white space. If you also specify a <list-file> using the -l option, this <element-list> is silently ignored.

-t <transaction-number>

Demotes all the versions created in the specified transaction.

Note that if you also specify an element or a list of elements, only those elements are demoted from the transaction.

For example, the following command demotes file_1 from transaction 15:

> accurev demote -t 15 file_1

Examples

Demote files commands.c and base.h to test_stream:

> accurev demote -S test_stream commands.c base.h

Demote the issue records listed in XML file demote_these_issues.xml (see the description of -Fx above for an example file):

> accurev demote -Fx -l demote_these_issues.xml

See Also

promote

AccuRev Admin Guide