defunct

remove an element from a stream

Usage

accurev defunct [ -c <comment> ]
	{ -l <list-file> | <element-list> | -e <eid> }

Description

The defunct command removes elements from active use in your workspace. That is, for each element you specify, it:

removes the file from your workspace tree

marks the element as (defunct) in the workspace stream

Since the file is gone, operating system commands such as ls (UNIX/Linux) or dir (Windows) won’t find a defunct element:

> dir /b d03.txt
File Not Found

But the stat and files commands will see the defunct element in your working stream:

> accurev files d03.txt
.\d03.txt        lemon_dvt_mary\8 (4\8) (defunct) (kept) (member)

defunct does not remove an element from the depot altogether. (In fact, no operation removes an element — that would violate AccuRev’s TimeSafe property.) And defunct does not make an element disappear for all users. defunct just removes an element from a particular workspace. The element remains visible in other streams and workspaces — at least for the time being (see Propagating Deactivation with the ‘promote’ command below).

Exclusive File Locking and Anchor-Required Workspaces

See File Locking in Workspaces.

Defuncting the Target of a Link

If you defunct the target of an element link, the link is automatically removed from your workspace. The indicators (missing) and (defunct-target) are added to the link’s status. When you promote the defunct target element to the backing stream, the link’s status changes from (defunct-target) to (nonexistent-target).

If you defunct the target of a symbolic link, the link is not removed from your workspace. The indicator (missing-target) is added to the link’s status.

Defuncting a Directory

If any of the elements you specify is a directory, defunct works recursively: it removes the directory itself and elements under that directory. Only the specified directory itself becomes (defunct); the files and directories below it are simply removed from the workspace tree, but do not become (defunct) in the workspace stream.

The precise result depends on whether any elements located below the defuncted directory are active:

If no element below the defuncted directory is active (in the workspace’s default group), the entire directory tree is removed from your workspace tree.

If one or more elements below the defuncted directory is active, those elements become stranded. A stranded element is in the default group, but there is no valid pathname to the element in your workspace stream. You can view your workspace’s stranded elements, identified by their element-IDs, with the command stat -i.

A stranded file or directory is not removed from your workspace tree. But the stat or files command lists the object as (external), since the workspace stream no longer has a valid pathname to the object.

Best Practice for Defuncting an Entire Directory Subtree

Based on the information in the preceding section, it follows that if you wish to defunct a multiple-level directory subtree, you should start at the top, not at the bottom. This eliminates unnecessary work, and it keeps lower-level elements from getting (stranded) status.

For example, suppose you wish to defunct the directory subtree starting at dir01. But before doing so, you first defunct the lower-level file dir01/sub02/file03.txt, and also the lower-level directory dir01/sub06. At this point, you have two element with (defunct) status:

.\dir01\sub02\file03.txt    wdgt_john\1 (16\1) (defunct) (kept) (member)
.\dir01\sub06               wdgt_john\1 (16\1) (defunct) (kept) (member)

If you then proceed to defunct directory dir01, those two elements will become stranded — the previous defunct commands made them “active” in the workspace, but the last defunct command caused them to have no pathname in the workspace:

.\dir01\sub02\file03.txt e:5 wdgt_john\1 (16\1)(defunct)(member)(stranded)
.\dir00\sub06          e:17 wdgt_john\1 (16\1) (defunct)(member)(stranded)

It would have been better not to work at all with the elements lower in the directory tree — simply defunct the highest-level element, dir01. This removes dir01/sub02/file03.txt and dir01/sub06 from the workspace (presumably, along with many other elements), but does not cause them to become stranded.

In general, use this procedure for defuncting a directory subtree:

Using the stat -d command, determine whether any element within the subtree is currently active in the workspace or stream.

Resolve the status of any active elements, using promote or purge.

Invoke defunct on the top-level directory of the subtree.

Propagating Deactivation with the ‘promote’ command

After defuncting an element, you use promote to propagate its deactivation to your workspace’s backing stream. (This parallels creating a new version of an element with keep, then propagating the version to the backing stream with promote.) After promotion, even the stat and files commands won’t see the defunct element.

• Defunct file foo.c

• Use a text editor to create a new file named foo.c

• Promote file foo.c

The result: element foo.c is removed from your workspace stream and from its backing stream, and your workspace contains an external file (not under version control) named foo.c.

Reactivation with the ‘undefunct’ Command

To reactivate a defunct element, use the undefunct command. You can do this either before or after you promote the deactivation to the backing stream. (For special cases, see the undefunct reference page.)

The Past and Future of a Defunct Element

In the future, an element that you have defuncted will be removed from all streams to which the change is promoted. When other people update their workspaces (or reference trees) that are backed by those streams, the element will be removed.

TimeSafe-ness means that you cannot change the past. This means that a defunct element remains in old snapshots of your stream. After the change is promoted to other streams, the element will remain in old snapshots of those streams, too. You can always get information about the element (if you know which stream it still exists in) using the hist command.

Options

-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.
–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 <eid>	The element-ID of the element to be defuncted. If you use this option, you can specify only one element. If you also specify a <list-file> or <element-list>, it is ignored.

Examples

Defunct two files:

> accurev defunct old_commands.c old_base.h

Defunct each of the elements listed in file go_away:

> accurev defunct -l go_away

Defunct the entire directory tree named alpha_project, located at the top level of the depot:

> accurev defunct /./alpha_project

See Also

hist

Techniques for Selecting Elements