Using the File Browser's Include/Exclude Mode
By default, a workspace contains a copy of each file under version control in a particular depot. (More precisely, a workspace contains a copy of each version in a particular stream.) But sometimes, you don't want or need a copy of every file -- for example, if your current assignment doesn't include "rebuilding the world" each night. The depot might contain many thousands of files, of which you might need only a small subset. The File Browser's Include/Exclude facility enables you to define and work with a subset of the depot's elements.
When you check (or clear) the Include/Exclude Mode checkbox, the File Browser immediately switches into (or out of) Include/Exclude mode. (There's no Ok button to press.) The File Browser works significantly differently in this mode, as described in the following sections.
See also ...
"Getting Only the Files You Need: the Include/Exclude Facility" in the AccuRev Concepts Manual
In Include/Exclude mode, both the Folders and Details panes show all elements in the workspace or stream. Elements that are currently excluded have (backed)(excluded) indicators in the Status column. For example, if top-level directory doc is excluded, the File Browser still shows it in both the Folders and Details panes:
You can navigate into an excluded directory. Its elements have (missing)(excluded) status, except for those that are stranded An element has '(stranded)' status in a workspace or stream if it's currently active, but there is no pathname to the element. This occurs when the element's directory (or a higher-level directory) is removed from the workspace or stream by the Defunct command or an exclude rule., which have (member)(excluded) status.
The File Browser gets a new pane, the rules pane, in Include/Exclude mode. This pane shows include and exclude rules that affect the current workspace or stream:
If the Show Inherited Rules checkbox is cleared, only the rules that were explicitly set for the current workspace are listed.
If the Show Inherited Rules checkbox is checked, the listing also includes rules inherited from higher-level streams. The Set in Stream column indicates which higher-level stream.
In Include/Exclude mode, the Details pane toolbar changes: most of the buttons for AccuRev's version-control commands -- Keep , Promote , Merge , etc.-- disappear. Instead, buttons for the several Include/Exclude commands appear. A few of the standard toolbar buttons remain, to aid you in navigating the depot and determining element history.
The sections below describe how to work in Include/Exclude mode:
In each depot, there is one hard-coded base rule The include/exclude rule that makes the top-level directory of a depot appear in the depot's root stream.: the depot's base stream has an include rule that specifies the depot's top-level (root) directory. This rule makes the depot's entire directory hierarchy visible in the depot's base stream.
Any number of rules can be added. Each rule applies to a particular pathname within the depot's directory hierarchy ("Element"), and applies at a particular level in the depot's stream hierarchy ("Set in Stream"). A rule set in a dynamic stream gets inherited by lower-level streams; but a rule for the same element in a lower-level stream or workspace overrides a rule in a higher-level stream.
Examples:
To remove an existing rule that appears in the rules pane:
Make sure that your File Browser tab is displaying the stream or workspace in which the rule was explicitly set (Set In Stream column). If necessary, open a new File Browser on that stream or workspace.
Right-click the rule, and select Clear Rule from the context menu.
When you remove a rule from a stream, the effect is immediate on the stream itself and on streams below it. The effect does not take place on workspaces below the stream until they are Update'd.
When you remove a rule from a workspace, the effect is immediate on the workspace itself: files are copied into the workspace tree if you remove an exclude rule; files are deleted from the workspace tree if you remove an include rule.
To leave Include/Exclude mode in a workspace or stream, clear the checkbox at the bottom of the Folders pane. The rules pane disappears, and the Details pane reverts to:
not displaying elements that have been excluded from the current workspace or stream
including the standard Details pane toolbar
The following commands are available in the File Browser's Details pane, when you have selected Include/Exclude mode:
Go to root
Have the Details pane display the contents of the depot's (and workspace's) top-level directory.
Up one level
Have the Details pane display the contents of the current directory's parent.
Include
Make the selected element(s) appear in the workspace or stream. If you specify a directory element, the entire subtree below it will appear in the workspace or stream, too.
As usual, the particular versions that will appear in the workspace or stream are the ones inherited from the backing stream (parent stream, basis stream) The stream that is just above a given workspace or stream in a depot's stream hierarchy. The given workspace/stream inherits versions from the backing stream..
Include Directory Only
Make the selected directory element(s) appear in the workspace or stream, but not any of the elements within the directory. You can use subsequent Include or Include Directory Only commands to make part of the directory's contents appear.
This command enables you to include files and directories that are deep in a depot’s directory hierarchy, without having to include lots of other, unwanted elements. If you include a file or directory that is several levels below an include-only directory, AccuRev automatically creates the necessary Include Directory Only commands required to "dig down" to the level of the desired data. [example]
A depot contains a tools subdirectory, which contains a src subdirectory, which contain a scripts subdirectory, which contains two subdirectories, perl and python. If you need only the python subdirectory, not the rest of the tools subtree, use these commands:
Invoke Include Directory Only on tools
Invoke Include on python
In the Rules pane, note that AccuRev automatically creates "incldo" (Include Directory Only) rules for the intermediate directories, src and scripts.
Include from Stream
Establish a cross-link An include/exclude mode operation ('Include from Stream') that includes an element in a workspace or stream, specifying an alternative backing stream for that element. Cross-linking a directory also cross-links the entire subtree below it. Cross-linked elements have (xlinked) status., making the selected element(s) appear in the workspace or stream. Instead of inheriting versions of the element(s) from the backing stream (as with the Include command), inherit the versions from the stream you specify in the Basis Stream dialog. [note ]
If you specify a directory element, the entire subtree below it will appear in the workspace or stream, too.
Note: as of AccuRev 4.5: in a stream, you cannot Promote to cross-linked elements; in a workspace, you cannot Keep (or Anchor, or Defunct, etc.) cross-linked elements.
Exclude
Remove the selected element(s) from the workspace or stream. For a workspace, the elements are deleted from the workspace tree The ordinary directory tree, located in the user's disk storage, in which the user performs development tasks and executes AccuRev commands.. If you specify a directory element, the entire subtree below it will be removed.
Properties
Displays information about the selected element: pathname, file type of current version, and element-ID.