purge

undo all of a workspace’s changes to an element

Usage

purge [ -c <comment> ] [ -s <stream> ] [ -I <issue-number(s)> [ -3 ] ]
{ <element-list> | [ -Fx ] -l <list-file> | [ --rebase] [ -i ] | -e <eid> }

Description

The purge command undoes all of the changes you have made to an element since you activated it in your workspace — that is, since you added the element to the workspace’s default group. Thus, purge cancels changes that you have not yet promoted to the backing stream:

  • It removes the element from your default group (deactivates the element in your workspace stream).
  • It replaces the file in your workspace with a copy of the version that was in the backing stream at the time of your most recent update. (But if you promoted one or more versions of the element to the backing stream since your most recent update, it restores the most recently promoted version to your workspace.)

purge does not actually remove any version of the element. (Nothing does that — AccuRev is TimeSafe.) You can still access versions that you created with keep, but then purged, with such commands as hist, co, and pop.

To remove an element from your workspace, use the defunct command.

Timestamp on the Restored Version

By default, each file copied into your workspace by this command has its timestamp set to the current time. If environment variable ACCUREV_USE_MOD_TIME is set, the timestamp is set to the time the version was originally created. (Note: that’s the time the version was created in some user’s workspace stream, not the time it was subsequently promoted to the backing stream.) Setting this environment variable may defeat an optimization in the stat command. See Optimized Search for Modified Files.

Effect of “purge” on “defunct”, “undefunct”, and “move”

purge undoes all changes that you have not yet promoted, including removal of elements with defunct and renaming/moving of elements with move. For example, if you defuncted or moved element foo.c (but didn’t promote the change), a subsequent purge makes foo.c reappear in your workspace. If you have defuncted a directory, thus removing all of its contents from your workspace, purging the directory will bring all of the contents back.

Similarly, if you purge an element that you’ve resurrected with undefunct, the element disappears again!

To undo a purge

AccuRev does not have a command to revert a purge operation, but the following workaround allows you to restore purged elements through the GUI. In the StreamBrowser:

  1. Create a new stream off the stream where the purge was performed and set its time stamp to 1 second before the purge operation.
  2. Right-click the new stream and choose Send to Change Palette. The pointer changes to include the Change Palette icon.
  3. Select the stream where the purge took place. The Change Palette appears.
  4. In the Change Palette, select the elements that were purged and promote them back to the stream where the purge was performed.

Exclusive File Locking and Anchor-Required Workspaces

If exclusive file locking is in effect for an element, purge returns it to read-only status. See File Locking in Workspaces.

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.

-s <stream>

Stream to purge changes from. Use this option with extreme caution. Like accurev promote -s, it removes pending (not yet promoted) changes from the specified stream. See the description of <element-list> below.

Note: Invoking purge -s causes the depot’s pre-promote-trig trigger to fire, because it changes which version of the purged element appears in the specified stream.

-I <issue-number(s)>

Bypasses the prompting for an issue record by the change package integration with AccuWork. 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"

-3

Specifies that any <issue-number> specified by the -I switch is a third-party ITS key rather than an AccuWork issue number.

-Fx

Signals that <list-file> (see the -l option) is an XML-format file, not a flat text file. Example:

<elements>
  <e eid="2"></e>
  <e eid="200"></e>
</elements>

-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 the file.

If you use this option, any <element-list> specified is silently ignored.

<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 purge changes from a non-workspace stream, then you must specify each name in <element-list> with a depot-relative pathname or an element-ID (-e option).

--rebase

Purge elements with changes that are already in the backing stream. You can use this option instead of specifying elements. When you perform a rebase operation on a stream or workspace, AccuRev purges elements if the current version is the same as what is in the backing stream or if the element is in an underlapped state. If you use the -i option with --rebase, AccuRev also purges stranded elements.

Note: You can also perform a rebase operation by running the rebase command.

-i

Remove stranded elements from the default group. If you want to identify any stranded elements that might be purged by the rebase operation, you can run stat -i prior to running --rebase.

-e <eid>

Operate on the element with the specified element-ID. You can use this option instead of specifying a list of elements. This option cannot be used in combination with the --rebase option, the -i option, the -l option, or an element list.

Examples

Purge changes you’ve made to files commands.c and base.h:

> accurev purge commands.c base.h

Promote a version of file tools.readme to stream tulip_test, then “undo” it:

> accurev promote tools.readme
Validating elements.
Promoting elements.
Promoted element \.\tools\tools.readme

> accurev purge -s tulip_test \.\tools\tools.readme
Purging element \.\tools\tools.readme

See Also

co, defunct, hist, rebase, undefunct

Techniques for Selecting Elements