Common Usage Scenarios

The following sections describe common usage scenarios and operations that you perform in the File Browser. More detailed information on the operations described in this topic appears elsewhere in this guide.

In this topic:

Editing a File

Perhaps the most common scenario is "non-conflicting development" — modifying a file that no one else is working on concurrently and saving your work. Initially, the Status column in the details pane shows the file's status as (backed): your workspace contains an unmodified copy of a version in the backing stream. The Version column contains a version-ID, indicating which backing-stream version it is:

To edit a file:

1. Select the file in the Details pane.

   Note: You cannot edit a file in Incoming Changes mode.

2. Click the Edit button () on the toolbar.

   Alternative: Right-click and choose Edit from the context menu. A text editor opens the selected file. Tip: You can use environment variable AC_EDITOR_GUI or EDITOR to control which text editor is opened. See ENV_VARS of the AccuRev CLI Guide for more information.

When you close the editor, the file's status changes to (modified). This indicates that you have modified the file in your workspace since the last time you synchronized the file in your workspace with the depot (with a keep or update command, for example). That is, you have changed the file in the local workspace, but not the element in the workspace stream.

You can edit the file as many times as you wish. The file's status remains (modified).

Back to top

Saving a File

To save your work in AccuRev, you use the Keep command. The Keep command creates a new version of the file in the workspace. The file's status changes to (kept)(member) to indicate that you have recorded a new version, and that the file is currently active in your workspace. (Active is an AccuRev term that means an element is a member of the workspace's default group. See The Default Group of a Workspace or Stream for more information.)

This version is said to record a content change to the file. The File Browser also has commands for performing namespace changes. See Renaming or Moving a File below for more information.

The Version column shows the version-ID of the newly created version. Note that this version is recorded in your private workspace (in this example, app_forms_dfoster); previously the Version column indicated that your workspace contained a version from the public backing stream (forms).

You can continue modifying the file and saving new versions in the depot with subsequent Edit and Keep commands. The file's status will alternate between (modified)(member) and (kept)(member). The persistence of the (member) indicator reflects the fact that the file remains active in your workspace until you promote your changes to the backing stream or undo your changes.

How to Keep a File

1. In the Outgoing Changes view of the workspace File Browser, select the files whose changes you want to save.

   Keep is also available in the Explorer mode. Consider using the Outgoing Changes mode because it presents all unsaved work in one place.

2. Click the Keep button () on the Outgoing Changes toolbar.

   Alternative: Right-click and choose Keep from the context menu. The Keep dialog box appears.

   

   Tip: The Action column lists the commands that AccuRev performs to save your changes.

3. In the Comment field, optionally enter a description about the version you are creating.

4. Click the Advanced button if you want to specify a file type or enable locking.

   Tip: AccuRev retains the comment you entered from your most recent keep.

5. If there are any files listed that you do not wish to keep at this time, clear that file’s Keep checkbox.
6. Click the Keep button to save changes for the selected files.

See Keep: Creating a New Versionfor more detailed information about keep.

Back to top

Renaming or Moving a File

In addition to tracking changes to the contents of files, AccuRev tracks namespace changes:

• To rename an element within the same directory, invoke the Rename command. (You cannot use this command to rename (external) objects.)
• To move a file to a different directory in the depot, right-click the file and select Cut from the context menu. Then right-click the destination directory in the Explorer pane (not the Details pane) and select Paste from the context menu. You can cut-and-paste a multiple-file selection in the same way.

You can also use the Rename command to move a file to a different directory; specify a relative pathname (such as ..\otherdir\myfile.c) as the new name for the file. See Renaming an Element for more information.

AccuRev records a namespace change to a file in the same way it records a content change: by creating a new version of the file in the workspace stream. The file's status changes to (kept)(member). Making a namespace change to a file activates it — creates a new version in the workspace stream and makes it a member of the workspace's default group — just like keeping a content change.

You can also rename and/or move a directory.

Back to top

Sharing Your Work with Others

Initially, the content changes and/or namespace changes you make to a file are recorded only in your workspace's private stream. This keeps your work isolated from your colleagues' work. When you are ready to share your changes with your colleagues, you promote the active version from your workspace stream to the backing stream. This makes your changes available to all workspaces that are based on the same backing stream.

Note how the version-ID in the Version column changes:

• Before the promotion, it indicates the particular version of the file that is active in your workspace. (In this example, version velo\2 and velo\1 for lists.xml and logic.xml, respectively; matrix.ini has no version specified because it is external — it has not been added to the workspace yet).
• After the promotion, it indicates that versions’ newly created version-IDs in the backing stream (in this example, dev).

Having been promoted to the backing stream, the file is no longer active in the workspace (is no longer in the default group of the workspace stream). Accordingly, it loses its (member) status and returns to being (backed) — its original status before you started working on the file. That is, the workspace returns to "inheriting" the version of the file currently in the backing stream — which happens to be the version you just promoted there!

How to Promote Your Changes

You use Promote to send the version of a file containing your changes to your workspace’s parent stream. This allows other users with workspaces on that same stream to get the changes in your version the next time they update their workspace. (Promote is also used to send versions from stream to stream. See Promote: Sharing Your Work for more information.)

To share the changes in your workspace with other users:

1. In the Outgoing Changes mode of the workspace File Browser, select the files whose changes you want to make available to other users.

   Tip: Promote is also available in the Workspace Explorer mode, but it can be more convenient to use the Outgoing Changes mode because this mode presents all changed work in one place.

2. Click the Promote button () on the Outgoing Changes toolbar.

   Alternative: Right-click and choose Promote from the context menu. If you have enabled change packages, AccuRev displays the Select Issue (Change Package) dialog box, which allows you to associate the files you are promoting with one or more issues in your issue tracking system (AccuWork or a third-party ITS, for example).

   

3. Select one or more issues from the list. You can also type numbers in the entry field, separated by a space. For example to specify issues 2 and 3, type 2 3.

4. Click Ok.

   The Promote dialog box appears.

   

   Tip: The Action column lists the commands that AccuRev performs to promote your version to the workspace’s parent stream. Note that you can promote new work that has not yet been added to AccuRev — the Promote operation performs the necessary Add action for you.

5. In the Comment field, optionally enter a description of the version you are creating.

   Tip: AccuRev retains the comment you entered from your most recent promote.

6. If there are any files listed that you do not wish to keep at this time, clear that file’s Promote checkbox.

7. Click the Promote button to send the version with your changes to the parent stream.

Back to top

Undoing the Changes

Inevitably, you sometimes decide not to share your changes with your colleagues — instead, you can decide to discard the changes altogether (by using the Revert to Basis command) or to move the changes out of a parent stream but make them active in a child stream or workspace (by using the Demote command).

Revert to Basis

The Revert to Basis command (right-click the element, and then choose Revert To... > Basis Version) undoes all the content and/or namespace changes you have made to an active file. The file's status reverts to (backed), and your workspace "rolls back" to using the version that it contained the last time the file's status was (backed). It might be a version that you brought into your workspace with a recent Update command; or it might be a version that you created in your workspace, then Promote'd to the backing stream.

See Revert: Undoing Changes for more information.

Demote

The Demote command moves an element version out of the default group of a stream, thereby rendering that version inaccessible in the stream. At the same time, that version is added to the default group of the child stream you specify as part of the demote process. In this way, the changes are not abandoned (as they are when you perform a Revert to Basis command) but, instead, are moved out of the parent stream and into a child stream.

The basic use of demote is to stop sharing changes so that the changes are no longer available to certain users. If, for example, a beta stream contains a new feature that causes the software to crash, you could demote the changes associated with that feature out of the beta stream so that your beta users no longer see those changes. The demote process enables you to remove problematic file versions from specific streams yet retain the code elsewhere so that it can be fixed and promoted again.

See Demote: Moving Elements Out of a Stream for more information.

Back to top

Changing a Directory

In addition to tracking changes to files, as discussed in the preceding sections, AccuRev tracks changes to directories. AccuRev's model for directory-level changes is simple, but somewhat different from the model used by the operating system (and by some other version-control systems). AccuRev considers the following to be changes to a directory:

• Renaming a directory
• Moving a directory to another location in the depot's directory hierarchy
• Deleting a directory

The following are not changes to a directory:

• Creating a new file (it is a change to the file itself)
• Renaming an existing file (it is a change to the file itself)
• Deleting a file (it is a change to the file itself)

Note that it is only changes involving a directory's pathname that are considered to be changes to the directory itself. Changes to a directory's contents are not considered to be changes to the directory itself.

You change a directory's pathname in the same way you change a file's pathname — with the Rename command (Edit > Rename) or with Cut and Paste commands. When you make such a change, AccuRev records a new version of the directory in the workspace stream. 

The new version-ID appears in the Version column of the Details pane (in this example, maint_dfoster\1). And the directory's status changes to (kept)(member) — just as it does for a file's namespace change.

Back to top

Deleting a File — Accidentally or Temporarily

An AccuRev workspace tree is an ordinary directory tree, typically located on your machine's hard drive. Nothing prevents you (or perhaps, some rogue cleanup script) from using operating system commands to delete one or more of the files under version control. On occasion, you may even want to delete some files temporarily — for example, to test the robustness of your build or installation procedure.

By definition, deleting a file at the operating system level makes it disappear from disk storage. Operating system tools, such as Windows Explorer or the UNIX ls command, will detect that the file no longer exists. But the file does not disappear from the File Browser display. AccuRev knows that the file should be in the workspace, because the file element still exists in the workspace's built-in stream. (The workspace stream is located in the AccuRev depot. It's unaffected by the operating system's delete-file commands.)

Accordingly, when a version-controlled file is deleted at the operating system level, the File Browser continues to list it, but indicates the file's status as (missing).

Note that the Version column continues to indicate which version of the file should be in the workspace. To restore that version, invoke the Populate command from the missing file's context menu.

Deleting a directory at the operating system level is similar to (but potentially more destructive than) deleting a file. The entire directory subtree is deleted from disk storage, and the directory is listed by the File Browser as (missing). To recover the entire directory tree, invoke the Populate command from the directory's context menu. Be sure to select the Recursive option from the Populate dialog.

See Delete: Deleting Elements from a Workspace Tree for more information.

Back to top

Deleting a File — Intentionally and Permanently

Sometimes, you want to delete a file permanently (see note). That is, you want the file to disappear from your workspace, and from other users' workspaces, too. The file might be related to a product feature that was cancelled. Or perhaps a code reorganization rendered the file unnecessary.

Deleting a file at the AccuRev depot level (rather than simply at the operating system level) is called defuncting, and is implemented by the Defunct command.

Defuncting a file removes it from the workspace's disk storage (that is, deletes the file at the operating system level). In addition, the Defunct command is recorded in the depot. It may be surprising at first, but AccuRev manages the defuncting of a file in the same way as it manages the creation of new versions. To AccuRev, defuncting is just another kind of change that can happen to a file:

• Defuncting "activates" a file in the workspace stream, recording the fact that you've made a change to the file. In addition to getting (defunct) status, the file gets the (kept) and (member) statuses, just as if you had performed a Keep command.
• AccuRev records the change as a new version of the file in the workspace stream.
• At first, the defuncting of a file is isolated to your own workspace. The file continues to exist in other users' workspaces.
• To "share" the defuncting of a file, you promote the change to the backing stream. This causes the file to disappear from your workspace stream, and from the File Browser display. The file will disappear from other users' workspaces when they refresh their workspaces using the Update command.

• As always, you propagate the change — in this case, removal of the file — throughout the depot by promoting the defuncted file from the backing stream to the depot's higher-level streams.

  Note: Defuncting is not really permanent (and the file is not even really gone)

  The Defunct command does not actually remove the file element from the AccuRev repository. Because AccuRev is TimeSafe, old versions of the file continue to exist in the repository. You can see such versions in snapshots of streams, in History Browser displays, etc. You can restore such elements with the CLI command undefunct.

See Defunct: Removing Elements from the Workspace for more information.

Back to top

Incorporating Others' Changes into Your Workspace

As you and your colleagues make changes to a project's code base, the contents of your private workspaces diverge more and more. It's a software-development best practice to periodically incorporate others' changes into your workspace, effectively resynchronizing the workspaces (partially or fully). The Update command performs this task, by copying versions that your colleagues have promoted to the backing stream into your workspace.

This is an oversimplification. For some elements, you must use the merge operation to incorporate other's changes into your workspace. For a complete discussion of the update operation, see Update: Keeping Your Workspace Current.

Back to top

Merging Your Changes with Someone Else's Changes

AccuRev supports concurrent development: two or more users can start with the same version of a file and make changes to that file independently — both content changes and namespace changes. After one of the users promotes his changes to the backing stream, each of the others must merge her own changes with the newest version in the backing stream, using the Merge tool. We describe here how to initiate a merge operation.

As you work on a file, keeping intermediate versions in your workspace, the file's status alternates between (modified) and (kept). At any point, you may notice that an additional indicator, (overlap), appears in the Status column. To make sure you notice, the File Browser displays the entry with a yellow highlight.

This means that a new version of the file has been promoted to the backing stream. Typically, one of your colleagues has edited the file and promoted her version to the backing stream. It may also be that someone has promoted a new version of the file to a higher-level stream, and the backing stream dynamically inherits the new version from its parent stream.

Whenever a file's status is (overlap), the Merge command is enabled. The execution of a Merge command concludes with AccuRev prompting you to keep the new version in your workspace.

When you promote this merged version to the backing stream, the file's status returns to (backed).

See Merge for more information.

Revert: An Alternative to Merge

Sometimes you might simply wish to undo the changes that created the (overlap) condition. In AccuRev, you accomplish an "undo" using the Revert command. Revert lets you:

• Remove all changes that you have made to these elements in your workspace, or
• Remove the change you made since you last did a keep on the file in conflict

See Revert: Undoing Changes for more information.

Back to top