AccuRev users sometimes confuse the two commands Populate and Update. These commands seem similar because they both bring new data into your workspace. But they are quite different, both in their usage pattern — most people use Update far more often — and in what they accomplish. Understanding the difference between these two commands will enable you to choose the right command at the right time (always useful!), and will deepen your knowledge of how AccuRev really works.
This chapter starts with a brief statement of the difference between Populate and Update, along with a few examples. Then, we present a full discussion of the data structures and mechanisms involved in these commands.
The essential difference between Populate and Update concerns time. Roughly speaking, your workspace contains an informal “baseline” (the contents of the shared backing stream, at a particular moment) plus “changes” (the modifications that you make to some of the files). The Update command advances the workspace’s baseline from the time of the workspace’s last update to the present moment. This incorporates into the workspace data recently placed in the backing stream by other team members.
Note: AccuRev actually tracks the workspace’s baseline in terms of transactions, not timestamps.
The Populate command doesn’t advance a workspace’s baseline at all, but leaves it “stuck in the past”. Instead, Populate simply restores the appropriate “old” version of one or more elements that are currently missing from the workspace.
The two commands also differ in their scope: Update always processes the entire workspace; Populate processes just a selected set of elements or directory subtrees.
The capsule description above uses imprecise language, such as “advancing the workspace’s baseline” and “old version”. The following description is more precise, using AccuRev-specific terminology. The terms are explained fully in section Data Structures Used by Populate and Update on page 21 below.
|
•
|
It advances the workspace stream’s update level to the depot’s most recent transaction — say, from current update level 32155 to new update level 34002. This allows a new set of versions — in this case, some or all the versions created by transactions 32156 through 34002 — to flow into the workspace stream from the backing stream.
|
By contrast, the Populate command changes the workspace tree only, not the workspace stream. In particular, it doesn’t change the workspace stream’s update level. Populate merely fixes a discrepancy between the workspace stream and the workspace tree: a certain version of a file is in the workspace stream, but there is no actual file in the workspace tree — that is, the file’s status is (missing). To fix this situation, you invoke Populate, which copies the version currently in the workspace stream to the workspace tree.
Note: It would be incorrect to conclude that Update never processes (missing) elements, and that Populate only processes (missing) elements. Examples 3 and 4 below show that exceptions exist for both these “rules”.
You’ve just finished a coding project, so you’re not actively working on any files in your workspace. Other team members create new versions of files red, white, and blue in their workspaces, then promote those versions to the team’s backing stream. You invoke the Update command, which copies the most recent versions of red, white, and blue from the backing stream to your workspace.
Since you have complete control over the files in the workspace tree, it’s easy to accidentally delete a version-controlled file with an operating-system command or a third-party tool. If you do this, AccuRev knows that the file should be there, because a version of the element still exists in the workspace stream. Thus, the File Browser continues to list the element, but shows it as (missing) from the workspace tree. You select the element and invoke Populate to fix the accidental deletion.
Update and Populate differ in how they handle elements that are active (are in the workspace’s default group). The Update story is simple: it never overwrites the file in the workspace tree. Populate usually doesn’t overwrite the file, but there are a couple of cases to consider.
|
•
|
It doesn’t need to overwrite a file that you’ve kept and not subsequently edited, because the active version in the workspace stream is identical to the file in the workspace tree.
|
|
•
|
 But if you have subsequently edited the file in the workspace tree, so that the element status is (modified)(member), then you can order Populate to overwrite the file and clobber those subsequent edits. This can also happen with a file that you’ve edited, but never kept, so that its status is (modified). |
Be careful — (modified) files will also be overwritten if you invoke Populate with both the Recursive and Overwrite options on a directory that directly or indirectly contains the active element.
You have a workspace that is completely up to date. You delete two files, named blue and green. Someone creates a new version of blue in another workspace, and then promotes it to your workspace’s backing stream.
If you select both blue and green in the File Browser, then invoke Populate, the two files that you deleted are restored to the workspace tree. This does not bring in the new backing-stream version of blue, because that version is not in the workspace stream — it’s too new, having been created after your workspace’s most recent update.
If you invoke Update instead of Populate, the workspace tree gets the new version of blue. No version of green is copied to the workspace tree, because Update only handles new versions — ones that enter your workspace stream as a result of advancing its update level.