revert

“undo” a promote transaction

Usage

accurev revert [ -I <issue-number> [ -3 ] ] [ -G ] [ -K ]  
	[ -S <stream> ]

accurev revert -t <transaction-number> [ -G ] [ -K ]  [-S <stream>]

Description

The revert command provides an “undo change” capability for dynamic streams. You have the choice of specifying a “traditional” revert operation, which requires you to be in a workspace based on that stream, or a “direct” revert operation, which does not require a workspace.

The “direct” revert takes fewer steps, but since it places the results of the revert directly into a stream, it is best used in simpler scenarios, or in a stream that does not propagate immediately to other users. For more complicated scenarios, where you want to test the results of the revert, it is better to use the workspace-based “traditional” revert.

revert doesn't actually remove any versions from the stream or transactions from the repository; that would be a violation of AccuRev's TimeSafe principle. Instead, revert creates a new version (using keep) of one or more elements. For a traditional revert, this keep is performed in your workspace; for a direct revert, the keep is done within the stream. If the version being reverted is the first version in a stream, the command defuncts that element.

The contents of the new version are the result of “subtracting out” a certain set of changes from the stream's current version:

• The changes that were added to the stream in a specified promote transaction, or
• The changes contained in a change package that is currently in the stream.

The “subtracting out” of content changes is performed by the same tool that performs a content-level merge. Submitting a different set of versions to this tool effectively implements a “reverse patch” algorithm (see below).

The revert command also “subtracts out” namespace changes. If the file name and/or parent directory were changed by the issue/transaction being reverted, and no one has moved or renamed the file since this issue/transaction, AccuRev moves the file back to its pre-issue/transaction directory and give it back its old name.

After a traditional revert command completes, you can verify the correctness of its work (and make further changes, if appropriate) in the workspace. Then, you can complete the “undo change to stream” process by promoting the new versions.

A direct revert promotes its changes directly into the specified stream. However, we recommend that you still build and test these changes in an updated workspace to verify the results.

Exclusive File Locking and Anchor-Required Workspaces

See File Locking in Workspaces.

Reverse Patch Algorithm

In a revert command, the changes in a specified set of versions are removed from a stream's current versions of those elements:

• When reverting a transaction, AccuRev regards each version in that transaction as being the head version of a patch, and removes all the changes in that patch from the element. The basis of the patch is the version of the element that was visible in the stream at the transaction before the one being reverted (that is, “revert transaction - 1”).
• When reverting a change package (specified by the number of the issue record containing the change package), AccuRev removes all the changes in each element's change package entry.

For each element it processes, the revert command uses the same tool as the merge command to perform the operation that removes a set of content changes from the current version. We use the term “reverse patch” to describe this process, but it's really just another instance of effectively modifying the merge algorithm by switching around the versions.

When the merge tool is invoked by revert:

• The version you selected when invoking the revert command is designated to be the closest common ancestor.
• The version currently in the stream is designated to be the “from version”.
• For revert by transaction, AccuRev determines the version that was in the stream just before the current version was promoted there; this version is designated to be the “to version”. For revert by issue, the common ancestor is the issue basis, and the “to version” is the issue head.

Just as with the merge command, you can use environment variable AC_MERGE_CLI to configure an alternative merge tool. See User Preferences.

revert finishes its work by invoking the keep command to preserve the results of the merge (reverse patch) operation.

In this algorithm's switching around of the versions, the basis version of the change package entry becomes the direct ancestor of the newly created version. This listing of the final keep transaction shows the result of removing a change package entry whose head version is 9/14 and whose basis version is 9/17.

transaction 214; keep; 2006/07/18 13:44:41 ; user: mary
  # Revert issue # 12
  \.\dir04\sub04\file07.txt 8/1 (8/1)
  ancestor: (9/14) reverted from: (9/23)-(9/17)

The “reverted from” data indicates that the changes made between versions 9/17 and 9/23 were added to the common ancestor version, 9/14. This is equivalent to subtracting the changes in the change package entry (9/14 - 9/17) from the current version, 9/23.

To revert a purge operation

AccuRev does not have a command to revert a purge operation. However, you can use the undo purge procedure documented in the purge command.

Options

-t <transaction-number>	Select all elements involved in the specified promote transaction. (No other kind of transaction can be reverted.) You must specify the transaction by number. Either -t or -I must be specified, but not both.
-I <issue-number>	For a typical revert operation, -I <issue-number> specifies the issue record whose change package is to be reverted. When performing a “traditional” revert, which requires the use of a workspace, you must specify either -t or -I, but not both. When performing a direct revert, you can specify the full -I (specifying both source and destination issue numbers) with -S.
-3	Specifies that the <issue-number> specified by the -I switch is a third-party ITS key rather than an AccuWork issue number.
-G	Use the graphical Merge tool to perform the merge if there are conflicts (which require human interaction).
-K	If the reverse patch operation does not involve any conflicts (and thus, no human intervention is required), perform this operation and keep the new version without asking for confirmation.
-S	Perform a direct revert of a change package in the specified stream, without using a workspace. This argument requires either an issue (-I) or transaction (-t) specification.

Examples

“Undo” promote transaction 489, by subtracting the recent changes in the versions promoted by that transaction.

> accurev revert -t 489

“Undo” the changes recorded in the change package of issue record #4519, bypassing reverse-patch confirmations when there are no conflicts:

> accurev revert -K -I 4519

Use a “direct” revert operation to undo the changes recorded in the change package of issue record #2763 in stream prod1_0_itr:

> accurev revert -S prod1_0_itr -I 2763

Use a “direct” revert operation to undo the changes recorded in the change package of issue record #15 in stream prod1_0_itr:

> accurev revert -S prod1_0_itr -I 15

See Also

anc, anchor, co, defunct