The Update Algorithm

The processing of the Update command is not as simple as “get all the new versions”, because AccuRev takes care not to overwrite version-controlled files that you have changed, but whose changes have not yet been preserved in the repository.

1.	AccuRev first searches the workspace tree for such “at-risk” files, by performing a CLI stat (file status) command on your workspace:

•

It uses the –n option to stat, which restricts the search to version-controlled files that you have modified but are not in the workspace’s default group — the status of such “non-member” files includes the (modified) indicator but not the (member) indicator. It’s safe to ignore default-group files, because these are never affected by an Update.

•	It uses Timestamp Optimization (TSO) to speed its search for files that have been modified in your workspace: it does not consider files whose timestamps have not changed since the last time the workspace was updated or searched for modified files.

•

To make sure that a file with a recent timestamp has actually been modified, AccuRev compares the file with the version currently in the workspace stream by performing a checksum. (This means that simply modifying a file’s timestamp with a touch command won’t prevent the file from being overwritten by Update. You have to make a real change to the file.)

2.

If the preceding step found any “non-member” files — modified, but not in the default group — the Update command in AccuRev releases prior to Version 4.6 terminated immediately, without updating any file. Starting in Version 4.6, the Update command can sometimes proceed, even in the presence of such files:

•	A non-member file that is not due to be updated, because there is no newer version in the backing stream, does not prevent the update from proceeding.

•

A non-member file that is due to be updated has (modified)(overlap) status. By default, the presence of one or more such files causes the update to terminate immediately, without updating any file. But you might be able to enable the update to proceed if you invoke an update option — update –m in the CLI, user preference Update Resolves Trivial Merges in the GUI. With this option invoked, the update proceeds only if a trivial merge can be performed for each file with (modified)(overlap) status. (The backing-stream version can be merged with the workspace-tree file automatically, because there are no conflicts that require manual intervention.)

3.	AccuRev notes the number of the repository’s latest transaction, and sets that number as the workspace’s target update level.

4.

AccuRev decides which recently created versions in the repository should be delivered to the workspace tree. A version is a candidate for delivery if it became visible in the workspace’s backing stream by one of the transactions between the workspace’s current update level and the newly set target update level.

5.

AccuRev attempts to deliver all those versions to the workspace tree. Each time it is about to overwrite a file in the workspace tree, AccuRev first makes sure it won’t be “clobbering” unpreserved changes: it checksums the existing file to confirm that it matches the current version in the workspace stream (the version at the current update transaction level).

Note: It is sometimes OK for the workspace tree to already contain the new version (the version at the target update level). See Incomplete Updates below for an explanation.

If a file about to be overwritten fails this checksum step, AccuRev reports a “crc mismatch” and the Update command terminates immediately. The most common cause of this error is your having overwritten the file in such a way that it gets an old timestamp. Such a file escapes detection in Step 1, but gets caught here — just in the nick of time to avoid being clobbered.

If the checksum succeeds, the file is safe to overwrite, so AccuRev updates it — finally! The update can be a replacement of the file’s contents, a change in its pathname, or both.

If AccuRev is processing files with (modified)(overlap) status (see Step 2 above regarding update -m), it automatically merges the backing-stream version with the file in the workspace tree, instead of simply overwriting the file. No checksum of the workspace-tree file is performed for such elements.

6.	If all the recently created versions identified in Step 4 were successfully delivered to the workspace

•	The target update level becomes the workspace’s current update level, indicating a successful, complete update.

•	The local TSO cache will be updated for all files that are updated.

Incomplete Updates

The Update command is not implemented as an atomic operation, and it is not recorded as an AccuRev transaction. Transactions are used to organize and serialize changes to the repository, not to the workspace trees that implement user “sandboxes”. An Update can take a significant amount of time, and is sometimes interrupted before it completes — by user request, by network failure, by loss of telephone connection, etc.

For purposes of discussion, assume that your workspace, talon_dvt_mary, has a current update level of 84, that the highest transaction in the repository is 109, and that 45 files in your workspace would be involved in a complete Update. You can monitor transaction levels using the CLI command show wspaces:

•	Before the update the output of show wspaces might include:

talon_dvt_mary c:\wks\talon_dvt xlnt 13 84 84 1 0

The first 84 indicates the workspace’s target update level; the second 84 indicates the current update level.

•	The Update command sets the target update level to 109, then proceeds. If Update processes all files successfully, it raises the current update level to the target:

talon_dvt_mary c:\wks\talon_dvt xlnt 13 109 109 1 0

But if the Update does not complete successfully, the target update level remains unchanged. A subsequent show wspaces reveals that the target update level differs from current update level:

talon_dvt_mary c:\wks\talon_dvt xlnt 13 109 84 1 0

The differing update levels — target vs. current — is the telltale sign that the most recent Update did not complete successfully.

Incomplete Update: Command Interrupted

Consider the case in which Update was interrupted — say, after it had processed 29 out of the 45 files to be updated. When a subsequent Update command is issued:

•	The checksum of the 29 files will succeed, because those files are already at the target transaction level.

•	The checksum of the 16 files will fail, because those files are still at the current update transaction level.

(See Step 5 above for a discussion of the checksum process.)

Incomplete Update: Checksum Failure

Now consider the case of an incomplete Update, due to one or more “crc mismatch” errors. Suppose that only 42 out of 45 files are updated, because 3 files fail the checksum match. You must fix the problem before issuing another Update.

If those three files had been overwritten by mistake, you can restore the proper versions using the Revert to Basis command (CLI: purge). Then, a second Update brings the new versions of those 3 files into the workspace.

Performing the “Fixup” Update

When it begins executing an Update command, AccuRev determines whether the preceding update of the workspace completed successfully or not:

•	The Update completed successfully if the target and current update levels are the same.

•	The Update was incomplete if the target and current update levels differ.

If the preceding update was incomplete, AccuRev performs two updates at once. First, it performs a “fixup” update that completes the preceding update; then it performs an additional update (if necessary), to process changes made to the backing stream after the incomplete update. During the “fixup” update, AccuRev avoids the unnecessary work: it does not retransfer files that were successfully delivered to the workspace during the incomplete update.

Example:

•	Your workspace’s current update level is 84, and the highest transaction in the repository is 109.

•	You issue an Update, but it fails to complete. At this point, the workspace’s target update level is 109, but its current update level is still 84.

•	You wait until after lunch break to reissue the Update command. At this point, the highest transaction in the repository is 137.

•	AccuRev performs a “fixup” update, which brings the current update level to the original target update level, 109. Then, it advances the target update level to 137 and performs another update. If this update succeeds, it advances the current update level to 137.