accurev promote [ -c <comment> ] [ -d | -k | -p ] [ -K ] [ -O ] [ -N ]
[ -s
<from-stream> [ -S
<to-stream> ] ] [ -g ] [ -q ]
[ -I
<issue-number(s)> [-3] ]
[ -l
<list-file> |
<element-list> | -t
<transaction-number> | -e
<eid> | -Fx -l
<XML-file> ]
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.
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.
|
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 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.
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:
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
If exclusive file locking is in effect for an element,
promote returns it to read-only status. See
File Locking in Workspaces on page 5.
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.
By default, promote sends changes from your workspace stream to its backing stream. The alternatives are:
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.
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.
Invocation of the promote command can activate one or both of the integrations 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:
(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 specified AccuWork issue record(s) are updated in one or both of these ways:
Specifies that any <issue-number> specified by the
-I switch is a third-party ITS key rather than an AccuWork issue number.
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.
Using the -N option prevents two unwanted things:
(not valid with -k or
-s) Selects all pending elements. If some of the pending elements have
(modified) status, use the
-K option, also.
<issues> <id>8</id>
<id>14</id>
<id>102</id>
</issues>
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.
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.
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.
Promote files commands.c and
base.h: