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 mktrig and AccuRev Triggers in the AccuRev Admin 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 from a time-based stream to its parent does not remove the elements from the default group of the time-based stream.
• 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.

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 its parent stream. Use the -s option to specify the “from” stream.

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.

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) in the AccuRev On-Line Help.

Options

 <issues>
      <id>8</id>
      <id>14</id>
      <id>102</id>
 </issues>

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