rmver

Removes a version from the version tree of an element

Applicability

Product

Command type

VersionVault

cleartool subcommand

Platform

UNIX®

Linux®

Windows®

Synopsis

rmver [ –f/orce ] [ –xbr/anch ] [ –xla/bel ] [ –xat/tr ]
[ –xhl/ink ] [ –xtask ] [ –dat/a ]

[ –ver/sion version-selector | –vra/nge low-version high-version ]

[ –c/omment comment | –cfi/le comment-file-pname | –cq/uery

| –cqe/ach | –nc/omment ] pname ...

Description

This command destroys information irretrievably. Using it carelessly may compromise your organization's ability to support old releases.

rmver deletes one or more versions from their elements. For each version, this entails the following:

  • Removal of the version object from the VOB database
  • Removal of all metadata items (labels, attributes, hyperlinks, and triggers) that were attached to the deleted version
  • Removal of all event records for the deleted version
  • (File elements only) Removal of the data containers that hold the deleted version's file system data

A destroy version event record is created for the element.

In general, a removed version is physically deleted from the VOB source pool. However, a removed version is logically deleted if it has a descendant and is managed by the z_text_file_delta or text_file_delta type managers. For more information about the type managers, see the type_manager reference page.

Behavior in snapshot views

In a snapshot view, rmver does not unload the element, but leaves a view-private copy of the element in the view. In other respects, rmver behaves the same in a snapshot view as it does in a dynamic view.

Deleted version IDs

The version ID of a deleted version is never reused. There is no way to collapse a branch to fill the gaps left by deleted versions. If a deleted version was the last version on a branch (say, version 6), the next checkin on that branch creates version 7.

A reference to a deleted version produces a not found or no such file or directory error.

Controlling the size of the vista.tjf file

The file vista.tjf records updates to the VOB that result from rmver operations. vista.tjf can grow very large. For information about limiting its size, read about the file db.conf in the config_ccase reference page.

Restrictions

ACL authorization

If ACLs are enabled, the principal must have the following permissions:
  • read-info on VOB object
  • read-info on element
  • rmver on element

Non-ACL authorization

You must have one of the following identities:

  • Version creator
  • Element owner
  • VOB owner
  • root (UNIX® and Linux®)
  • Member of the VersionVault administrators group (VersionVault on Windows®)

Locks

An error occurs if one or more of these objects are locked: VOB, element type, element, branch type, branch, pool (nondirectory elements only).

If an instance of a locked label type is attached to the version or to a branch containing the version, you cannot remove the version unless you have one of the following identities: VOB owner, root, or member of the VersionVault group.

Mastership

(Replicated VOBs only) Your current replica must master the branch containing the version you are removing.

Other

You cannot delete a version from which someone currently has a checkout. You cannot delete version 0 on a branch, except by deleting the entire branch. (See rmbranch.)

Options and arguments

Confirmation step

Default
rmver prompts for confirmation before deleting anything.
–f/orce
Suppresses the confirmation step.

Deleting interesting versions

Default
rmver does not delete a version to which a version label, attribute, or hyperlink is attached, or at which a branch begins.
–xbr/anch
Deletes a version even if one or more branches begin there. In the process, those branches (including all their versions and subbranches) are also deleted.
–xla/bel
Deletes a version even if it has one or more version labels.
–xat/tr
Deletes a version even if it has one or more attributes.
–xhl/ink
Deletes a version even if it has one or more hyperlinks. This also destroys the hyperlink object, thus modifying the other object to which the hyperlink was attached.
Important: Using this option can delete merge arrows (hyperlinks of type Merge) created by the merge command, which may destroy essential metadata.
–xtask
Deletes a version, even if it is associated with one or more CLM tasks. If you do not specify this option and tasks are attached to the specified version, an error is returned.

Data-only deletion

Default
rmver deletes both the version object in the VOB database along with associated metadata and the corresponding data container in a source storage pool.
–dat/a
Deletes only the data for the specified version, leaving the version object, its subbranches, and its associated metadata intact. In particular, this option preserves event records and enables continued access to the configuration record of a DO version.
Important: Using this option implicitly invokes the –xbranch, –xlabel, –xattr, and –xhlink options, as well. That is, the data container is deleted even if the version has a label, attribute, or hyperlink attached or has a branch sprouting from it.

Specifying the versions to be removed

Default
None.
–ver/sion version-selector
For each pname, removes the version specified by version-selector. This option overrides both version-selection by the view and version-extended naming. For syntax details, see the version_selector reference page.
–vra/nge low-version high-version
For each pname, removes all versions between (but not including) the two specified versions. low-version and high-version must be on the same branch and are specified in the same way as version-selector.
pname ...
(Required) One or more pathnames indicating the versions to be removed, as follows:
  • A standard or view-extended pathname to an element specifies the version in the view.
  • A version-extended pathname specifies a version, independent of the view.

Use –version or –vrange to override these interpretations of pname.

Event records and comments

Default
Creates one or more event records, with commenting controlled by your .versionvault_profile file (default: –nc). See the comments reference page. Comments can be edited with chevent.
–c/omment comment | –cfi/le comment-file-pname |–cq/uery | –cqe/ach | –nc/omment
Overrides the default with the option you specify. See the comments reference page.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Delete the version of msg.c in the view.

    cmd-context  rmver msg.c
    Removing these versions of "msg.c": /main/1
    Remove versions? [no]     yes

    Removed versions of "msg.c".

  • Delete version 1 on the rel2_bugfix branch of element util.c, using a version selector to specify the version, suppressing confirmation prompts.

    cmd-context  rmver -force -version \main\rel2_bugfix\1 util.c

    Removing these versions of "util.c":
    \main\rel2_bugfix\1
    Removed versions of "util.c".

  • Delete version 3 on the main branch of element Makefile, even if it has labels and/or attributes. Use a version-extended pathname to specify the version.

    cmd-context  rmver -xlabel -xattr Makefile@@/main/3
    Removing these versions of "Makefile":
    /main/3 (has: labels, attributes)
    Remove versions? [no]     yes

    Removed versions of "Makefile".

  • Delete all versions between 0 and LATEST on the main branch of element hello.c.

    cmd-context  rmver -vrange \main\0 \main\LATEST hello.c

    Removing these versions of "hello.c":
    \main\1
    \main\2
    Remove versions? [no]     yes
    Removed versions of "hello.c".

  • Delete version 2 on the main branch of util.c, even if there are one or more subbranches off that version. (The subbranches, if any, are also deleted.)

    cmd-context  rmver -xbranch util.c@@/main/2
    Removing these versions of "util.c":
    /main/2 (has: subbranches)
    Remove versions? [no]    yes
    Removed versions of "util.c".