Techniques for Selecting Elements

The following sections describe techniques for specifying the elements to be processed by a command, based on AccuRev status, on filename, or both.

Selecting Elements Based on their Status

A few command-line options are recognized by many of the accurev commands, and work identically (or nearly identically) in each command. These options act as filters, selecting a subset of the depot’s elements based on their element status. This makes it easy to select sets of elements for a command to operate on. You can use these filter options alone or in combination with filename arguments. Examples:

Invoke the keep command on all items in the current directory:

accurev keep *

Invoke the keep command on all items in the current directory with (modified) status.

accurev keep -m *

Invoke the add command on all items in the current directory with (external) status and a .png filename suffix.

accurev add -x *.png

Invoke the stat command on all items in the workspace, in all directories.

accurev stat -a

The following sections describe useful scenarios of selecting a set of elements in your workspace, based on the elements’ current status. Be sure to read the section Performance Considerations for Element-Selection Commands, also.

Selecting Modified Elements

The –m option selects modified elements. By default, it selects all modified elements. When combined with other selection criteria, it narrows the selection to just the modified elements. This is how we obtained the earlier example with keep. To keep all modified elements:

accurev keep -m

To keep all modified elements in the current directory:

accurev keep -m *

To simply find out which elements match a given set of criteria, use the stat command. As in the previous example, to list all modified elements in the current directory:

accurev stat -m *

Selecting Kept Elements

To select all kept elements, use the –k option. This command promotes all the elements in the depot that you’ve kept:

accurev promote -k

When combined with other selection criteria, –k narrows the selection to just the kept elements. To promote all kept elements in the current directory:

accurev promote -k *

Selecting Members of the Default Group

Each workspace and stream has a default group, a list of its “active” elements:

•	In a workspace, these are the elements that you’ve “officially” activated with an accurev command (anchor, co, keep, move, defunct, undefunct, revert), but have not yet promoted to the backing stream. The default group does not include elements that you’ve simply modified with a text editor.

•	In a (non-workspace) stream, the active elements are those that have been promoted to the stream from a workspace below it (or from another non-workspace stream), but have not yet been promoted to the parent stream.

The purge and promote commands remove elements from the default group.

You can restrict a command to using the elements in the default group, by using the –d option. This is very useful when you’re working on a large depot: determining the contents of the default group is a relatively quick operation, whereas examining all the elements in the depot is comparatively time-consuming. For instance, if you are working on a depot with 1000 files but you only have 10 files in your default group, using the options –m –d to select the modified elements in the default group only has to check 10 files. This will run much faster than using just the –m option, for which accurev must examine all 1000 files.

Selecting Non-Member Modified Elements

If you want to make the best use of the default group, you will periodically need to add modified elements to the default group if they aren’t already in it. You can select non-member modified elements with the –n option. To add all non-member modified elements to the default group:

accurev co -n

Selecting Pending Elements

The end goal of any change is to promote that change to the backing stream. All changes, whether kept or not, are considered to be pending. Pending is short for “pending promotion”. The pending option is necessary because –k does not select modified elements and –m does not select kept elements. To list all elements that are pending promotion in the current workspace:

accurev stat -p

Selecting Overlapping/Underlapping Elements

Elements that you have changed and have also been changed in the backing stream since you last updated your workspace are called overlapping. Before you can promote these elements, you must merge your changes with the new changes in the backing stream. To get a list of all overlapping elements:

accurev stat -o

When you are ready to do the merges, you can do a merge of all overlapping elements very simply:

accurev merge -o

Underlap status is similar to overlap status, in that an element has changed in your workspace and also in the backing stream. With underlap, the changes in your workspace version have already been promoted to the backing stream (from another workspace, or from a stream elsewhere in the depot’s stream hierarchy). In many cases, the most appropriate action is to use the purge command to “undo” the changes in your workspace. In other cases, a merge-promote sequence is most appropriate.

To get a list of all underlapping elements:

accurev stat -U

To purge the changes in underlapping elements, specify them on the command line or in a list-file:

accurev purge blink.java BlinkProj.doc

Note: purge restores the version of an element that was in the backing stream at the time of your workspace’s most recent update. You might need to perform another update to bring the version causing the underlap status into the workspace.

Selecting Objects That AccuRev Doesn't Know About

Files and directories that haven't been processed with the add command are called external. These can be selected with the –x option. This is useful for creating new elements — that is, placing files under version control:

accurev add -x

Before doing so, it is a good idea to find out which files AccuRev considers to be external:

accurev stat -x

Selecting All Elements

To select all the elements in a depot, use the –a option. (If you use –a, you cannot also list elements on the command line.) This command displays the status of all of the elements in a depot:

accurev stat -a

The –a option does not include external objects.

Performance Considerations for Element-Selection Commands

The commands in the preceding sections all follow the same pattern: find all the elements in your workspace that satisfy a certain condition, and perform an operation on the selected set of elements. Many of these commands require that AccuRev consider every file in your workspace, even the ones that you haven’t placed under version control (for example, editor backup files, files produced by software builds). If your workspace contains many thousands of files, such operations can be time-consuming.

These are the command options that require a full-workspace search:

–p elements that are pending promotion to the backing stream
–m elements that you’ve modified (and possibly kept, too)
–n element that you’ve modified but have not kept
–o elements with overlap status
–U elements with underlap status
–B status up the backing chain, including deep overlaps
–x files that you have not placed under version control (external)
–M elements under version control, but no file appears in your workspace (missing)

AccuRev provides optimizations that help to speed the performance of workspace and stream searches. See the files and stat reference pages for more information.

Selecting Elements Using Filename Patterns

Whenever you need to specify one or more filenames in an accurev command, you can:

•	(UNIX/Linux) specify them using standard wildcards, which the shell will expand properly.

•	(Windows) specify them using one or more filename patterns (“wildcards”). You can also combine patterns and complete filenames in the same command.

The accurev program recognizes the following filename patterns:

*

Matches any 0 or more characters.

?

Matches any 1 character.

[aekz]

Matches a, e, k, or z.

[e–k]

Matches e, f, g, h, i, j, or k. Note: do not mix uppercase and lowercase.

{one,two,seven}

Matches any of the three strings: one, two, or seven.

/ or \

Matches any directory-separator character, even if it’s the “wrong one” for the client machine. For example, src/do_*.java matches src\do_something.java on a Windows client.

Examples:

•	The following command displays the status of the files rln_4.1.1.htm, rln_4.1.2.htm, and rln_4.1.3.htm:

accurev stat rln_4.1.?.htm

•	The following command displays the status of the three files listed above, along with others such as rln_4.htm, rln_4.5.txt, and rln_4.1.3k-ubuntu.htm:

accurev stat rln_4*.{txt,htm}

But it would not display the status of file rln_4-windows.chm.

•	The following command creates new versions of five files, color_f, color_g, ..., color_j.

accurev keep color_[f-j]

Combining File-Status Filters with Filename Patterns

If you use a file-status filter in the same command as a filename pattern, the pattern is applied before the filter. For example:

-k *.doc

... specifies this two-step selection process:

1.	Select all elements in the current directory that have the suffix .doc.

2.	Select the subset of those elements that have (kept) status.

Selecting Elements Using Element-IDs

With numerous commands, you can specify a single element using its integer element-ID, which is unique within its depot. For example:

accurev cat -v isox/4 -e 4823

To determine the element-ID of an element, run the stat –fe or hist command on the element.