incl

set rule to include elements in a workspace or stream

accurev incl [ -s <stream> ] [ -b <backing-stream> ] [ -fx ]
{ -l <list-file> | <element> }

The incl command includes the specified element (either a directory or a file) in a particular workspace or stream. If you don’t use the -s option to name a stream, incl operates on the workspace containing the current working directory.

You may need to use a complete depot-relative pathname — starting with /./ (UNIX/Linux) or \.\ (Windows) — to specify the element to be included. A path must exist in the workspace or stream from the depot’s root directory to the element you wish to include. That is, all the directories between the root directory and your element must be included in the workspace or stream. One or more incldo commands might be needed to satisfy this requirement.

Note: As of Version 4.6, an incl command automatically causes AccuRev to execute incldo commands, as necessary, to include intermediate directory levels in the workspace or stream.

Including a directory element causes it to appear in the workspace or stream, along with all the files and subdirectories below the directory element. Including a file element causes just that one file to appear.

Inheritance of Inclusion

When you include elements in a workspace, the appropriate versions of the files are immediately copied to the workspace tree.

When you include elements in a higher-level stream, the inclusion instantly applies to streams below it in the depot’s stream hierarchy. The inclusion also applies to workspaces below the stream, but the elements don’t appear in a workspace until you update it. This inheritance of inclusions down the stream hierarchy stops at snapshots and at dynamic streams whose basis time precedes the time of the inclusion. The element inclusions don’t apply to the snapshot (which is, by definition, immutable) or to that time-based stream.

Creating an Empty Workspace Before using ‘incl’

Using mkws with the -i option (to create an initially empty workspace) is a useful technique for organizations that use incl and excl to control which elements appear in a workspace.

Cross-Links: Including Elements from a Stream other than the Backing Stream

The -b option enables you to change the backing stream for individual elements. The element is included in your workspace (or in the dynamic stream you specify with -s); when a new version of the element arrives — through an update for a workspace, or through automatic inheritance for a dynamic stream — the version comes from the -b stream (or snapshot), not from the original backing stream.

The incl command is said to create a cross-link from your workspace (or the -s stream) to the -b stream. The files and stat commands list a cross-linked element as having (xlinked) status. When you cross-link a directory element, the entire subtree of elements below it also become cross-linked.

Cross-linking provides read-only access to elements. You can view or execute the contents of the version that is brought into your workspace or stream. But you can’t use commands like keep or promote on the element.

As of AccuRev 4.5: in a stream, you cannot promote cross-linked elements; in a workspace, you cannot keep (or anchor, or defunct, etc.) cross-linked elements.

Notes: for cross-linking to succeed, the element must have been present in the stream specified with -b at the time your workspace was last updated. In a time-based stream, you cannot create a cross-link to another time-based stream (or to a snapshot) whose basis time is “in the future” with respect to your stream.

Options

-s <stream>

Apply the include rule to the specified stream. When using this option, you cannot specify the element to be included with a simple filename; use its depot-relative pathname instead.

-b <backing-stream>

For this element, create a cross-link (xlink) from the current workspace (or from the -s stream) to the specified dynamic stream or snapshot. The element must already appear both in your workspace and in the “target” stream or snapshot.

-fx

Display the results in XML format.

-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 a list-file.

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

An element name. If you also specify a <list-file> using the -l option, this <element> is silently ignored.

Examples

Include the python subdirectory of the previously excluded tools directory in the current workspace:

> accurev incl \.\tools\python

Include the src\mmgt subdirectory in the current workspace, getting its versions from the snapshot widget_V3.4:

> accurev incl -b widget_V3.4 \.\src\mmgt