2. AccuRev® Command-Line Reference : promote

promote
propagate a version from one stream to another stream
Usage
accurev promote [ -c <comment> ] [ -d | -k | -p ] [ -K ] [ -O ] [ -N ]
[ -s <from-stream> [ -S <to-stream> ] ] [ -q ]
[ -I <issue-number(s)> [-3] ]
{ -l <list-file> | <element-list> | -t <transaction-number> | -e <eid>
| -Fx -l <XML-file> }
Description
The promote command sends a stream's changes, involving one or more elements, to its parent stream. The most common use of promote is to send new versions, created in your workspace stream with the keep command, to the backing stream. This has the effect of taking your private changes and making them public.
Other changes that can be promoted include: renaming and moving of elements, creation of new elements, and defuncting/undefuncting of elements.
Promotion-Related Triggers
AccuRev defines these triggers related to the promote command:
A pre-promote-trig trigger fires on the client machine before the promote operation takes place. You can use this kind of trigger to control promotions, perhaps cancelling the promotion in certain cases.
A server-post-promote-trig trigger fires on the server machine after the promote operation takes place. Typically, this kind of trigger notifies one or more users of the promotion.
The server_preop_trig trigger fires on the server machine before the promote operation takes place, if the trigger has been configured for the depot in which the elements to be promoted reside.
For more information on triggers, see the mktrig reference page and AccuRev Triggers of the AccuRev Administrator’s Guide.
Keep and Promote
Basic development with AccuRev involves editing a file element in your workspace, then using keep to create a new version in your workspace stream. This stores a permanent copy of the edited file in the depot. The new version that keep creates in your workspace stream is called a real version, because it's directly associated with the new file in the depot.
By contrast, promoting a kept version doesn't store a new file in the depot. Instead, it creates a virtual version in the parent stream. This version is just a reference to (or an alias for) the real version. The virtual and real versions have identical contents: the file originally stored in the depot by the keep command. Thus, the effect of promote is to make an existing real version available at the next higher level in the stream hierarchy.
Directory Promotion
Directory elements need to be promoted only after they are first add’ed to the depot and after they are renamed. AccuRev automatically promotes a directory that doesn’t yet exist in the backing stream when you promote any element within that directory.
Promotion and the Default Group
When you promote an element from a “child” workspace or stream to its “parent” stream, the element is removed from the default group of the child stream, and are added to the default group of the parent stream. That is, the elements become inactive in the child stream, and active in the parent stream. Exceptions:
Promoting an “old” version of an element (see Promoting an ‘Old’ Version below) does not remove the element from the default group of the workspace.
Promotions to destinations other than the immediate parent stream do not remove elements from the default group of the “child” stream. See Stream Promotion below.
Promoting an ‘Old’ Version
A common AccuRev scenario involves using keep several times to preserve intermediate versions of a file, then using promote to make the most recently kept version public. But after you’ve kept (say) five versions, you might decide it’s the third version that deserves to be promoted, not the fifth and final version. There’s no need to “roll back” your workspace to the older version. Instead, you can specify that older version as the version to be promoted.
Note: As always, AccuRev may disallow the promotion of your version because changes made in other workspaces need to be merged into your version. Use the -O option to suppress this “is a merge required?” check.
When you promote an older version, the most recent version of the element remains active in your workspace. (That is, it remains in the workspace’s default group.) This enables you to promote a stable, older version of an element, while continuing to work on a newer version that is not yet ready to be promoted.
To promote an older version of an element that is active in your workspace, specify a transaction number with the -t option. This must be a keep transaction that took place in your workspace, AccuRev promotes all the versions created in that transaction:
> accurev promote -t 53
Validating elements.
Promoting elements.
Promoted element \.\src\brass.c
Promoted element \.\src\brass.h
Exclusive File Locking and Anchor-Required Workspaces
If exclusive file locking is in effect for an element, promote returns it to read-only status. See File Locking in Workspaces.
When Promotion Fails
If two or more developers have workspaces that are backed by the same stream, they’re in a first-come-first-served race to promote versions to the backing stream. If somebody else has already promoted his version of any of the files you are promoting, the entire promote command is cancelled. For each such file, you must merge your colleague’s changes (the changes that he managed to promote before you did) into the version in your workspace. After keeping the merged file, you can promote it to the backing stream.
Stream Promotion
By default, promote sends changes from your workspace stream to its backing stream. The alternatives are:
Any non-workspace stream’s changes can be promoted to a stream that is not its parent. Use both the -s and -S options, to specify the “from” and “to” streams.
Note: In this case, termed a cross-promotion, the promoted versions are not removed from the default group of the “from” stream.
If a depot’s stream hierarchy is deep, several promotions will be required to propagate an element’s changes from their origin (the workspace stream) to their final destination (the depot’s base stream).
At any stream level, a merge (merge -v) may be required to enable promotion to the next level.
What Promotion Doesn’t Do
Promotion affects the workspace stream (located in the depot), but it has no effect on the files in the workspace tree (located in your disk storage). In particular, a promoted element is not removed from your workspace. The file remains in your workspace and is writable. You can immediately edit it without doing any sort of “check-out” or having to run the co command.
Integration with AccuWork
Invocation of the promote command can activate the change-package-level integration between AccuRev’s configuration management and issue management facilities. Before the promote operation is performed, you are prompted to enter one or more AccuWork issue record numbers:
Validating elements.
Please enter issue number ?:
(Use the -I option to specify issue record number(s) on the command line and bypass this prompt.) Enter a number, or multiple numbers separated by SPACEs. After the elements are promoted, the change-package-level integration updates the change package (Changes subtab) of the issue record.
For more information, see The Schema Editor (Administrators Only) of the AccuRev On-Line Help.
Options
–c <comment>
Specify 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 of the workspace (or more generally, the child stream). When used with the -t option, see the -d -t explanation below.
-e <eid>
Operates on the element with the specified element-ID. This is useful for promoting stranded elements to the backing stream. Use stat -i to list stranded elements. If you also specify a <list-file>, <element-list>, or <transaction-number>, it is ignored.
-I <issue-number(s)>
Bypasses the prompting for an issue record by the change-package-level integration with AccuWork. (See Integration with AccuWork above.) The integration uses the number you specify after -I. You can specify multiple issue records as a SPACE-separated list, enclosed in quotes:
-I "349 411 413"
Note: This option does not invoke a promote-by-issue operation. Rather, the versions you are promoting are applied to the specified issue record(s). For promote-by-issue, use the -Fx option.
-3
Specifies that any <issue-number> specified by the -I switch is a third-party ITS key rather than an AccuWork issue number.
-k
Selects all kept elements. (Not valid with -l, -s, or -p.)
-K
If a specified element has (modified) status, first keep the element, then promote it. If you specify a comment with -c, it becomes part of both the keep and promote transactions. Note that server_preop_trig is called twice: once for the keep operation, and once for the promote operation.
-N
Asserts that the version(s) to be promoted contain all the changes in the change package specified with -I (or with the change-package-level integration between AccuRev and AccuWork). AccuRev verifies the “all changes are included” assertion before promoting the version(s); if the assertion is false, the command is cancelled.
No modification is made to any change package; the only change is that an existing change package (the one specified with -I) is now “in” an additional stream (the one to which you’re promoting the versions).
Typical use case: you’ve fixed a bug in stream A, and now you wish to incorporate the fix into stream B, as well. You use the patch command on one or more elements, sending the changes you made in stream A to a workspace based on stream B. Then, you promote -N the new versions to stream B.
Using the -N option prevents two unwanted things:
-p
(not valid with -k or -s) Selects all pending elements. If some of the pending elements have (modified) status, use the -K option, also.
-q
Suppresses the execution of a workflow transition that would otherwise be executed when an issue enters a stream. Applicable only if the stream into which the issue is being promoted has a workflow rule restricting entry to issues in a specific workflow stage and a transition has been specified for that stage in the workflow rule. See the AccuRev Web User Interface User’s Guide for more information on implementing a workflow.
-s <from-stream>
Promote from the specified stream to its parent stream (or to the stream specified with -S). <from-stream> cannot be a workspace stream. See the description of <element-list> below.
-S <to-stream>
Promote to the specified stream. You must also specify the “from” stream, with -s.
-O
Override: (1) if there’s a name discrepancy, change an element’s name in the “to” stream to match its name in the “from” stream; (2) promote a version even if a merge would normally be required with the version in the “to” stream.
Defaults: (1) don’t change an element’s name in the “to” stream (just promote the new version); (2) cancel the entire promote transaction if any version requires a merge.
-Fx -l <XML-file>
Specifies a set of issue records with an XML-format text file. Example:
<issues>
      <id>8</id>
      <id>14</id>
      <id>102</id>
</issues>
The versions to be promoted are the head versions in the issues’ change packages (Changes subtab).
 
-l <list-file>
Process 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 filenames. Wildcards are not expanded. There is no provision for comment lines in a list-file.
If you use this option, you cannot also specify -k, and any <element-list> specified is silently ignored.
Please note that using the plain text output of the mergelist command as the <list-file> when cross-promoting (defunct) elements will cause errors. Use the -Fx option for the mergelist command to include version information in the output, and use the resulting XML file to promote instead.
<element-list>
One or more element names, separated by whitespace. If you also specify a <list-file> using the -l option, this <element-list> is silently ignored.
If you use -s to promote from a non-workspace stream, then each name in <element-list> is interpreted relative to the top-level directory of the depot. Typically, a simple filename like base.h won’t be valid; instead, use a pathname like src/include/base.h. Alternatively, use a full depot-relative pathname, like /./src/include/base.h.
-t <transaction-number | time>
Promote all the versions created in the specified transaction. See Promoting an ‘Old’ Version above. If you also specify a <list-file> or <element-list>, it is ignored. When used with the -d option, see -d -t explanation below.
-d -t <transaction-number | time>
 
Promote all active transactions up to and including the specified transaction or time. In other words, all active elements versions at the specified transaction id or time. The element versions that will be promoted will be the same as returned by the "accurev stat -d -t <transaction | time>" command.
Examples
Promote files commands.c and base.h:
> accurev promote commands.c base.h
Promote all elements that you have kept, but not yet promoted:
> accurev promote -k
Promote the head versions in the change packages of the issue records listed in XML file promote_these_issues.xml (see the description of -Fx above for an example file):
> accurev promote -Fx -l promote_these_issues.xml
Promote all active elements of a stream <s> at or up to transaction <t>:
> accurev promote -s <s> -d -t <t>
 
See Also
co, demote, keep, merge, mktrig
Techniques for Selecting Elements

Micro Focus