File Browser: Working in the Searches Pane
The File Browser can organize the contents of a workspace or stream by AccuRev status The state of an element, from a version-control perspective, in a particular workspace or stream., instead of by directory location. When you click one of the items in the Searches pane (e.g. Kept), the File Browser searches the entire workspace or stream for objects that meet that search criterion, and displays those elements in the Details pane. You can perform commands on these objects, using the toolbars and menus.
File Browser searches enable you to see "just the files you care about", instead of all the files in your workspace. [note ] Which files do you care about? Roughly speaking, a workspace contains a copy of its backing stream -- often, the entire source base -- which might include hundreds or thousands of files. But for a given development project, you'll probably modify only a handful of the files. You may not need the other files at all; or you may need them for general reference, or to enable you to perform software builds and tests in the workspace.
The searches are not mutually exclusive: some objects may be selected by more than one search criterion -- for example, Kept and Pending: every object selected by a Kept search will also appear in the results of a Pending search.
See also ...
Another way to concentrate on just the files you care about: the include/exclude facility
To perform a search of the entire workspace, dynamic stream, or snapshot on which you opened the File Browser, just click one of the search criteria in the Searches pane. AccuRev performs the search and displays the resulting set of elements in the Details pane.
You can perform as many searches as you like; the File Browser remembers the results of the most recent search of each kind. So, for example, you might:
Click the Kept search criterion to search for files with (kept) status in your workspace.
Click the Overlap search criterion to search for files with (overlap) status in your workspace.
Click the Kept search criterion again.
Instead of performing another search, the File Browser just displays the results of your previous search for files with (kept) status. You can refresh the display to have the File Browser perform the Kept search again, in order to take into account recent changes.
The cache of search results is maintained until you close the File Browser tab.
The Search in Selected Folder checkbox at the bottom of the Searches pane enables you to restrict any search to the subtree of the folder that is currently selected in the Navigation pane. If you check or clear this checkbox when the Details pane already contains the results of a search, AccuRev automatically performs the search again in the restricted (or unrestricted) context. If Search in Selected Folder is checked, the folder context appears in the Searches pane banner:
A search can be almost instantaneous or not, depending on the number of elements in the workspace or stream. During a longer search, AccuRev displays a progress box. If you click the Run in Background button, the progress box is replaced by an indicator in the lower right corner of the GUI window:
The indicator disappears when the search completes.
The Searches pane contains these search criteria:
Pending
(workspace only) Select elements whose status includes either (modified) or (kept). These are elements that have had a content change A change to the contents of a file element, recorded in a new version created with the Keep command. For a symbolic-link element, a change to the target pathname is a content change. For an element-link element, a change to the target element is not considered a content change to the link. See namespace change. or a namespace change A change to the pathname of a file or directory element: either renaming the element in place or moving the element to a different location in the depot’s directory hierarchy..
Modified
(workspace only) Select files whose status includes (modified). This indicates a content change that has not yet been preserved with Keep (but may have followed a previous Keep).
Kept
(workspace only) Select files whose status includes (kept). These are files whose content changes have all been preserved with Keep, or elements with namespace changes (Rename or Defunct command).
(workspace only) Select files whose status includes (modified) but not (member). These are files that have content changes, but are not in the workspace's default group. They have not been activated with a Keep or Anchor command since the file's last update or promotion.
Default Group
Select elements whose status includes (member). These are elements in the workspace's default group, for which you've entered one of these commands: Keep, Rename, Defunct, Anchor .
Overlap
Select elements whose status includes (overlap) -- the current version in the parent stream is not an ancestor of this version. This means there might be content changes A change to the contents of a file element, recorded in a new version created with the keep command. See namespace change. or namespace changes A change to the pathname of a file or directory element: either renaming the element in place or moving the element to a different location in the depot’s directory hierarchy. in the parent stream version that are not present in this version.
You must perform a Merge with the parent stream version before you can Promote your version. If you're in a dynamic stream, you must perform the Merge in the Change Palette.
Deep Overlap
Select elements that satisfy the Overlap search criterion in the current workspace or stream, along with Overlap elements in the parent stream, in the grandparent stream, and so on -- all the way up the depot's stream hierarchy.
Underlap
Select elements whose status includes (underlap) -- the current version in the parent stream is not an ancestor of this version, but the parent-stream version already contains all the changes of this version. In most cases, you can safely Revert to Backed your version, so that you'll get the parent-stream version the next time you Update the workspace. Alternatively, you can perform a merge An operation that combines the contents of two versions (contributors) of the same element. To merge the contents of text files, AccuRev uses a '3-way merge' algorithm: it compares the two files line-by-line with a third file, the version that is the closest common ancestor of the other two. Merging of namespace changes also takes into account the closest common ancestor., just as with (overlap)-status elements.
Modified in Default Group
(workspace only) Select elements whose status includes both (modified) and (member). This is the intersection of the sets of files selected by the Modified and Default Group search criteria.
External
(workspace only) Select files and directories that exist in 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., but have never been placed under version control The discipline of keeping track of the changes made over time to a file or directory. with the Add to Depot command.
Missing
Selects elements that should be present, but aren't. That is, there's a version of the file or directory in the workspace stream, but the file or directory was removed 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. by an operating system command or some non-AccuRev program.
Notes (click to view):
Missing files in a sparse workspace
In a sparse workspace (deprecated in newer versions of AccuRev), only a subset of the depot's elements are loaded into the workspace tree. In such a workspace, elements that have not been loaded have the status (missing), and so are listed by this search.
Stranded
Select the elements in the default group that have become 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. See defunct.. In the Details pane, a stranded element is identified by its element-ID, since it has no pathname in the workspace or stream.
Notes (click to view):
Here's the most typical scenario for stranding a file in a workspace:
Create a new version of a file with Keep. This places the file element in the workspace's default group.
Remove the file's parent directory with Defunct. With the parent directory gone, there's no pathname in the workspace to the file element.
For more information, see "Version Control of Namespace-Related Changes" in AccuRev Technical Notes.
Defunct
Selects the elements in the default group of a workspace or dynamic stream whose status is (defunct).
Many of the File Browser's searches described above require that AccuRev consider every file in your workspace, even the external A file or directory that is located within a workspace tree but has not been placed under version control has 'external' status. objects that you haven't placed under version control (e.g. editor backup files, files produced by software builds). If your workspace contains many thousands of files, such operations can be time-consuming. AccuRev can use optimizations during a full-workspace search to significantly improve search performance, and to reduce "visual clutter":
The set of elements located by a search are displayed in the Details pane. The operations that you can perform on these elements are described in the Details Pane topic.
Notes (click to view):
Selecting all the objects located by a search
Selecting all objects in the Details pane can be particularly useful after a search. For example, to promote all files that you've saved with Keep:
Click Kept in the Searches pane
Select one file in the details pane
Press Ctrl-A to selects all the elements in the Details pane
Invoke the Promote command.
A file can disappear from the Details pane if you change it in a search-related way. For example, after you promote all the files displayed by a Kept search, the files' status changes from (kept) to (backed). Accordingly, the files disappear from the Kept search results.