archive

prepare to transfer version container files to offline storage

Usage

accurev archive [ -E <element-type(s)> ] [ -i ] [ -p <depot> ]
[ -a | -I <stream-category(s)> ] [ -s <stream> ]
[ -t <transaction-range> ] [ -c <comment> ] [ -R ]
{ [ -Fx ] -l <list-file> | <element-list> }

Description

The archive command processes versions of one or more file elements, shifting the versions’ container files from normal status to archived status. It also moves the container files from the depot’s file storage area to a special gateway area (located under the depot directory).

archive determines the set of versions to archive as follows:

•	Start with a particular set of file elements, which you specify as command-line arguments in the <element-list>, or in a list-file (plain-text or XML format). You can include directories in this list; in this case, use the -R option to include the recursive contents of those directories.

•	Optionally, take the subset of versions whose element type matches the specification made with -E. (Note that different versions of an element can have different element types.)

•	Optionally, take the subset of versions that were created in a particular stream (-s, for example, your current workspace stream). You can also archive versions from all streams in the depot (-a).

•	Optionally, take the subset of versions created in a specific transaction, or range of transactions:

•	single transaction: -t <number>

•	range of transactions: -t <number>-<number>

•

In addition to the multiple subsettings of versions described above, you can use the -I option to include versions in the set, based on where in the stream hierarchy they are referenced. For example, you can include versions that were not originally included in the set because they are referenced by one or more snapshots.

Dry Run Capability

Using the -i option (in addition to the other options described above) generates an XML-format listing of the final subset, but does not perform any actual archiving work. It is highly recommended that you do this before actually archiving any versions.

For a complete description of archiving, see Archiving of Version Container Files of the AccuRev Administrator’s Guide.

Options

-i

List the versions that would be archived (in XML format), but don’t actually archive them.

–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.

-E <element-type(s)>

Restrict the archive operation to elements of one or more element-types: text, binary, and/or ptext. To specify multiple types, use a comma-separated list (default: all specifies all element types). Examples:

-E ptext,binary
-E "text, ptext"

-p <depot>

Select the depot to archive (default: the depot of the current workspace).

-s <stream>

Restrict the archive operation to versions in the specified stream (or snapshot, or workspace). Default: archive versions in the current workspace stream.

If you use this option, you must identify the elements to be processed using depot-relative pathnames.

-I <stream-category(s)>

Include additional versions in the archive operation, from one or more categories of the depot’s streams. (Note that a version can fall into more than one of these categories.) Specify multiple categories as a comma-separated list.

•	depot — From each stream in the depot, include all versions except the last one (most recently created). This includes dynamic streams, snapshots, and workspace streams.

•	snapshots — Include versions that are in one or more snapshots, but are not currently active in any dynamic stream.

•	deactivated — Include versions that are the currently selected versions in one or more dynamic streams, snapshots, or workspace streams that have been deactivated with the remove command.

•	all — same as -a; allows you combine -a and -I options.

•	allInHierarchy — Include all versions of a specified element underneath the specified stream hierarchy, except for those versions that are shared with another hierarchy. If no element is specified, all elements in the specified stream hierarchy are included.

•	unsafe — Include versions that AccuRev would normally prevent you from archiving. This “force” option implies that you realize the potential complications that could arise from archiving these versions.

-a

Archive all versions of the element(s), even versions that are currently visible in users’ workspaces and active streams. This option overrides (and is mutually exclusive with) the -I option.

-t <transaction>[ .<count> ]

 

-t <transaction> - <transaction>[ .<count> ]

The first form specifies one transaction, or a specified number of transactions up to (i.e. preceding) and including a particular transaction, for example: 23695 or now.5.

The second form specifies a range of transactions; the optional suffix truncates the listing after the most recent <count> transactions. You may need to use quotes in composing the argument following -t; the entire argument must be interpreted by the command shell as a single token. You cannot use the now or highest keyword in the interval specification.

For the archive command, a transaction can be represented in the following ways:

•	Time keyword: now

•	Transaction number as a positive integer: e.g. 146 or 23965

•	Transaction number keyword: highest

-R

Recurse into each directory specified in <element-list> or <list-file>.

-Fx

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

<elements>
   <element location="\.\dir07\sub01\file01.txt"/>
   <element location="\.\dir07\sub01\file02.txt"/>
   <element location="\.\dir07\sub01\file14.txt"/>
</elements>

The -Fx option must precede the -l option on the command line.

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

Examples

Note: In the XML-format listings below, the v and r attributes report the virtual version and real version, respectively.

List the versions with element-type binary, created in the current workspace and located below the current working directory, that are eligible for archiving:

> accurev archive -E binary -i -R .
<elements>
   <e
      location="/pngs/sb/sb_dftgrp_1.png"
      v="5/1"
      r="5/1"/>
   <e
      location="/pngs/sb/sb_dftgrp_2.png"
      v="5/2"
      r="5/2"/>
   <e
      location="/pngs/sb/sb_dftgrp_2.png"
      v="5/1"
      r="5/1"/>
   <e
      location="/pngs/sb/sb_dftgrp_3.png"
      v="5/3"
      r="5/3"/>
     ...
</elements>

List the versions of element sb_dragdrop_3.png, created in the current workspace in transactions 1-25, that are eligible for archiving:

> accurev archive -i -t 1-25 sb_dragdrop_3.png
<elements>
   <e
      location="/pngs/sb/sb_dragdrop_3.png"
      v="5/2"
      r="5/2"/>
   <e
      location="/pngs/sb/sb_dragdrop_3.png"
      v="5/1"
      r="5/1"/>
</elements>

Archive the versions listed in the preceding example:

> accurev archive -t 1-25 sb_dragdrop_3.png

*** WARNING! *** WARNING! ***

The archive command removes files from the depot. If you do not back up
the archives created by this command, the files may be lost permanently.
...
Are you sure you want to proceed [yes/no] ? [] yes

Archiving complete.
Make sure you store the archives in a safe place for
future use. Backup is recommended.
The archives were stored to:
Archive dir : C:/Program Files/AccuRev/storage/depots/img/archive_gateway/out
Machine : biped
Transaction : 33

List the versions of element file_8.txt in the s1 stream hierarchy that will be archived if you specify -I allInHierarchy. Note that versions that are used in another stream hierarchy are not listed and will not be archived. In this example, version v="1/1", r="5/1" is used in stream S2, and so will be excluded from the proposed archive.

> accurev archive -i -I allinhierarchy -s s1 file_8.txt

   <e
      location="/file_8.txt"
      v="2/2"
      r="5/2"/>
   </elements>

List the versions of element file_8.txt in the s1 stream hierarchy that will be archived if you specify -I allInHierarchy,unsafe. Note that versions that are used in another stream hierarchy are now listed and will be archived.

> accurev archive -i -I allinhierarchy,unsafe -s s1 file_8.txt

<elements>
   <e
      location="/file_8.txt"
      v="2/2"
      r="5/2"/>
   <e
      location="/file_8.txt"
      v="1/1"
      r="5/1"/>
</elements>

See Also

reclaim, unarchive

Techniques for Selecting Elements

Archiving of Version Container Files of the AccuRev Administrator’s Guide.