Kinds of Changes Involved in an Update
Deciding which elements to update
The principal purpose of an AccuRev workspace is to provide an isolated location for performing development tasks. The changes you make do not affect your colleagues until you decide to make them public, using the Promote command. Likewise, the changes that others make do not immediately affect your workspace. You must execute an Update command to bring versions created (and then promoted) by your colleagues into your workspace.
You invoke the Update command in the File Browser, using the File > Update command or a button above the Folders pane.
During execution of the Update command, a progress window appears. A user preference controls how this window is used.
At its simplest, an update just copies versions of some file elements from your workspace's 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. into the workspace. For example, your colleagues may have edited the contents of files colors.java and main_menu.java, created new versions of them in their workspaces, then promoted the versions to the common backing stream. When you invoke Update, the new versions of those two files are copied from the depot to your workspace, overwriting the older versions of the file.
In addition to incorporating such content changes A change to the contents of a file element, recorded in a new version created with the keep command. See namespace change. into your workspace, Update incorporates 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. :
renaming of a file
moving of a file to another directory
creation of new files and directories
defuncting A particular kind of change to an element in a workspace or stream: that the element is to be deleted. The element disappears from the workspace or stream. Somewhat counter-intuitively, it also becomes active in the workspace or stream, because defuncting is a change that can be promoted to the parent stream (or can be undone with a purge operation). A defunct operation is originally recorded as a new version of the element in some workspace. Promoting this version up the stream hierarchy causes the element to disappear from the higher-level streams.of existing files and directories
AccuRev tracks namespace changes in the same way as content changes -- by saving each change as a new version in your workspace. If you Rename file colors.java to colours.java, the change is recorded as a new version of the file. Changing the name again, to hues.java, creates another new version.
Similarly, defuncting file rgb.java creates a new version of the file in your workspace.
Note: Rename'ing a modified file before Keep'ing it
The following sections provide an overview of how Update works.
The basic Update strategy is to leave the files you're working on undisturbed, and to copy any new versions of other files into the workspace. This enables the workspace to provide the safety of isolation, while still "keeping in touch" with other users' progress.
Roughly speaking, Update partitions the files in your workspace tree The ordinary directory tree, located in the user's disk storage, in which the user performs development tasks and executes AccuRev commands. into two categories, to determine which are candidates for updating:
Files that you're currently working on. AccuRev uses the concept of default group The set of elements that are currently active in a particular workspace or stream. to keep track of the files you're working on. Files are placed in the default group when you process them with such AccuRev commands as Send to Workspace, Keep, and Rename. These files are not candidates for updating, because it would overwrite your changes.
All the other files. The files that you're not currently working on are candidates for updating. AccuRev will update all such files for which a more recent version exists in the backing stream.
But things are not quite this simple. You might have edited other files, too, without preserving the changes with the Keep command. Such files have (modified) status.
In many cases, no one else has been working on those files. If no new versions of the (modified)-status files have been created in the backing stream since your most recent Update, the update proceeds, leaving those files alone.
But suppose one or more of the files does have a new version in the backing stream. In this case, the file's status is (modified)(overlap). Update won't simply overwrite the file with the backing-stream version, but it can attempt to 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. the file with the backing-stream version:
If user preference Update Resolves Trivial Merges is not selected, Update terminates immediately with an error box:
If user preference Update Resolves Trivial Merges is selected, Update determines whether a merge can be performed automatically on all files with (modified)(overlap) status. If so, the update proceeds. If not, the update terminates with an error box:
Notes (click to view):
Members of the default group are "active" elements
AccuRev documentation often uses the term active An element is said to be active in a workspace or stream if a new version of the element has been created there, and that version has not been either (1) promoted to the parent stream or (2) purged from the workspace or stream. See default group, backed, passive. to describe the elements that are members of the default group.
Anchor-required workspaces and exclusive file locking
By default, AccuRev allows you to edit any file in a workspace at any time -- it doesn't require you to perform a "check out" operation on a file before editing it. This provides convenience and flexibility, but the edited files (with "non-member" status) can abort an Update. You can use the anchor-required An optional setting on a workspace, specifying that the workspace’s file elements are to be read-only until the user performs a checkout operation (GUI: Anchor command; CLI: anchor or co command). workspace and/or exclusive file locking An AccuRev feature that enforces serial development: when a file becomes active in one workspace, an exclusive file lock prevents the file from becoming active in sibling workspaces. feature to ensure files never get "non-member" status, thus guaranteeing that Update will always proceed. See File Locking.
Determining which elements need to be updated: performance note
This step is efficient and speedy. Update needs to consider only the elements that were involved in transactions recorded since the workspace's previous update. Only these transactions can contain changes that have not yet been incorporated into the workspace.
Update next applies both content changes and namespace changes to elements in the workspace:
It applies content changes to file elements by copying the backing-stream versions from the repository to the workspace tree. For (modified)(overlap)-status files, it merges the backing-stream version with the file in the workspace tree.
It handles namespace changes to file and directory elements by creating, removing, renaming, and/or moving objects in the workspace tree.
After it has completed the updating of versions in the workspace, Update changes the values of two workspace parameters:
scan threshold The time at which a workspace's most recent search for modified files was initiated. Such searches are performed by the Update command and by certain File Browser searches. See update level.: the more recent this value, the more effective the timestamp optimization used both by Update and by certain File Browser searches.
update level The most recent (highest-numbered) transaction whose changes have been incorporated into a workspace, through an update operation. See scan threshold, transaction level, target transaction.: after an update, the workspace is "up to date as of transaction N "; N is the workspace's update level. The higher this value, the fewer transactions your next invocation of Update will need to examine, in order to determine which elements need to be updated.
Sometimes AccuRev is not able to complete an Update operation, typically because a file cannot be overwritten due to permissions, or because it is open in another application. In this case, you will see an "Update Failed" warning. Use the View Log File button on this dialog to display the details of the failure, which should allow you to troubleshoot and correct the issue.
For a more detailed description of how Update does its work, see section "The Update Algorithm" in AccuRev Technical Notes.