AccuRev® Command-Line Reference : purge

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> | -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 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.
The ‘purge’ Command and the ‘pre-promote-trig’ Trigger
Purging a version from a dynamic stream, but not a workspace, fires the depot’s pre-promote-trig trigger (if such a trigger has been defined). In particular, purge works like promote in activating the transaction-level integration between AccuRev and AccuWork. See AccuRev Triggers on page 71 of the AccuRev Administrator’s Guide (and in particular, Transaction-Level Integration Trigger on page 73).
Use the -I option to specify one or more issue records, bypassing the integration’s issue-record prompt.
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: the Scan Threshold on page 240.
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. In the GUI:
1.
Create a new stream off the stream where the purge occurred and set the time stamp to 1 second before the purge operation.
2.
3.
Select the elements that were purged and promote them back into the stream.
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 on page 5.
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 transaction-level 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="4">
  <e eid="7">
</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. 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).
-e <eid>
Operate on the element with the specified element-ID. You can use this option instead of specifying a list of elements. This is useful for removing stranded elements from the default group. Use stat -i to list stranded elements. If you also specify a <list-file> or <element-list>, it is ignored.
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, undefunct
Techniques for Selecting Elements on page 13
 

AccuRev, Inc.
Phone: 781-861-8700
Fax: 781-861-8704
support@accurev.com