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> }
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.
|
•
|
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.
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.
By default, promote sends changes from your workspace stream to its backing stream. The alternatives are:
Note: In this case, termed a
cross-promotion, the promoted versions are
not removed from the default group of the “from” stream.
At any stream level, a merge (merge -v) may be required to enable promotion to the next level.
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:
(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.
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.
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.
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.
-t <transaction-number | time>
Promote files commands.c and
base.h: