Getting Work Done with the CLI

AccuRev does not force you to proceed with your software development work in any particular way. The workflow described in the following sections shows how you can put the AccuRev CLI to good use, but it certainly isn’t the only way to get your work done.

Creating a Workspace

Use the accurev mkws command to create a new workspace. Using command-line options, you must specify three parameters:

Name of backing stream (–b option): Each workspace is associated with (or “based on”, or “backed by”) one of the depot’s streams. If a depot represents a particular development project, then a stream represents a sub-project. The backing stream acts as a “data switchboard”, organizing the sharing of your changes to files with changes made by other members of your development team.

You can name any dynamic stream or snapshot (static stream) as the backing stream for the new workspace. You cannot choose a workspace stream — a workspace cannot be based on another workspace. For example, to specify the stream named brass_dvt as the backing stream:
```
-b brass_dvt
```
Name of new workspace (–w option): AccuRev identifies each workspace by a simple name, which must be unique across the entire repository. That is, two workspaces cannot have the same name, even if they belong to different depots. You can specify any name; accurev will automatically add the suffix _username to it (unless you type the suffix yourself). If your username is derek, then these two specifications are equivalent:
```
w brass_dvt_derek
-w brass_dvt
```
As the above example shows, the AccuRev convention is to name a workspace after its backing stream, with the username suffix providing uniqueness. This convention makes it easy to set up a backing stream and a set of like-named workspaces, one for each user:

backing stream:
brass_dvt

workspaces:
brass_dvt_derek
brass_dvt_mary
brass_dvt_john
Location of workspace tree in file system (–l option): A workspace’s name is a simple identifier, stored in the AccuRev repository. You must also decide where the workspace will be located on your hard disk (or elsewhere in file storage to which you have access). If you specify a pathname that does not yet exist, accurev creates an empty directory at that location. If you specify an existing directory, accurev “converts” it to a workspace — the files in the existing directory tree become versions of the elements in the backing stream (if their pathnames match), or become external files (if their pathnames don’t match those of existing elements.

Examples:
```
C:\dvt_work	(Windows)
C:\ac_workspaces\brass_dvt
H:\Projects\Colorwheel\mary

/usr/projects/mary/brass_dvt	(UNIX/Linux)
/workspaces/ColorWheel/mary
```

In addition to these mandatory specifications, there are options for controlling other aspects of the new workspace:

Workspace kind (-k option): A standard/default workspace (–kd) contains a copy of each element in the backing stream. By default, each user can edit the files in his workspace without having to issue a “check out” command, and irrespective of the status of the file in other users’ workspaces. The –ke option provides exclusive file locking: after you use co or anchor to start working on a file, users in other workspaces sharing the same backing stream are prevented from working on the same file.
Text-file line terminator: By default, AccuRev uses the line terminator appropriate for the client machine’s operating system whenever it copies a version of a text file into the workspace. You can force the workspace to get text files with UNIX/Linux (–eu) or Windows (–ew) line terminators.

Placing Files Under Version Control

The files in a workspace are not automatically version-controlled. After all, there are many files that you don’t want to version-control: text-editor backup files, intermediate files and log files produced during software builds, files you may have downloaded from the Internet, etc. A file that’s in a workspace but is not under version control is said to have external status.

To place one or more external files under version control, use the add command:

accurev add Red.java White.java Blue.java

(The files must already exist; add won’t create an empty file for you.)

You can have add search for all external files — throughout the entire workspace — and convert them to elements:

 accurev add -x

This also places the directories containing those files under version control (if they aren’t already). Using add –x makes it very easy to convert an existing directory tree into a workspace (see Creating a Workspace), then place all the files in that directory tree under version control.

Editing Files in a Workspace

By default, the files in a workspace are always writable. You can edit the files at any time, using a text editor, an IDE, or any other application.

If you’re in a workspace in which you must “check out” a file before editing it (aee File Locking in Workspaces), version-controlled files are maintained in a read-only state until you invoke the co or anchor command on them.

Checkpointing — Saving Private Versions

At any time, you can keep the changes you’ve made in one or more files. The keep command creates an official new version of a file. This includes making a permanent copy in the depot of the file’s current contents. At any point in the future, you can revert to this version. This “save it just in case” procedure is commonly called checkpointing.

But keep does not make the new version public — it remains private to your workspace. Nobody else will see your changes yet. You can keep as many private versions (i.e. checkpoint the file as many times) as you want, without affecting or disrupting other people's work.

Here’s an example of the simplest form of the keep command:

accurev keep testrun.pl

You’ll be prompted to enter a comment string, which can span multiple lines. It might be easier to include short comments in the command itself:

accurev keep -c "shorten timeout" testrun.pl

You can specify multiple files in a single command. If you want to keep a large number of files at once, it’s probably easiest to place their pathnames in a text file (say, my_filelist), and use the –l option:

accurev keep -l my_filelist

The keep command can use file-status filters. For example, this command keeps all files — throughout the entire workspace — that you’ve modified but not yet kept:

accurev keep -m

Comparing Versions of a Text File

The standard development procedure for a version-controlled file consists of these steps:

Edit the file, then use the keep command to create a new, private version.
Repeat the preceding step as many times as desired (or not at all).
Make the (most recent) private version public, using the promote command.

As you’re working on a file using this procedure, you’ll often want to compare the current contents of the file with other versions. The diff command does the job.

For example, you might want to know, “what changes have I made to file Red.java since the last time I performed a keep on it?” This command shows the answer:

accurev diff Red.java

If you’ve created several intermediate versions with keep, you might want to ask, “what changes have I made to file Red.java since I started working on it?”. Often, this question is answered by comparing your file with the version in the backing stream:

   accurev diff -b Red.java

These are just some simple examples; you can use diff to compare any two versions of a text file element. By default, diff output looks like this:

diffing element \.\doc\procfiles.py
56a57
>       ### -f option (formerly -l):
59c60
<       if optdict['-l']:
---
>       if optdict['-f']:
62c63
<               for line in f.readlines():
---
>               for line in f():

Using an environment variable, you can configure diff to use a third-party file-difference program.

Making Your Changes Public

To make your work on a file available to others, you promote the (most recent) private version in your workspace to the backing stream. That is: keep creates a private version, and promote turns it into a public version.

(Other users, whose workspaces have the same backing stream, can incorporate your promoted versions into their workspaces with the update command. (See Incorporating Other Users’ Work into Your Workspace.)

As with keep, you can specify particular files to promote on the command line or place their names in a text file:

accurev promote testrun.pl	(on the command line)
accurev promote -l my_filelist	(in a text file)

You can specify a comment string with –c, but it’s not required. (With keep, it is.)

File-status filters work with promote, too. For example, this command promotes all files — throughout the entire workspace — for which you’ve used keep to create new versions:

accurev promote -k

Concurrent Development — Working Well with Others

The essence of concurrent development (or parallel development) is enabling an entire team of developers to work with the same set of files at the same time. To avoid chaos, each user gets his own private set of files (that’s your workspace), which are copies of a “master” set of files (that’s the backing stream).

AccuRev tries to stay out of your way as much as possible. But as you proceed with development in your private workspace, you’ll often want to perform several configuration management operations:

Determining the current status, from AccuRev’s viewpoint, of one or more elements in your workspace.
Determine the past statuses — that is, the development history — of one or more elements.
Determining what other team members are working on — and whether anyone else is working on a particular file at the same time as you.
Incorporating other teams members’ changes into your own workspace.

The following sections describe the AccuRev commands that implement these operations.

Determining the Status of Files

Each file in a workspace has an AccuRev status, one or more keywords that describe its development state in that particular workspace. In large part, status is determined by comparing the file with the version in the backing stream. Some examples:

If the file in your workspace is the same as the version in the backing stream, the status is (backed). This occurs when you haven’t edited the file at all. It also occurs when you keep a new version of the file, then promote that version to the backing stream.
If you edit a file without keeping it, its status is (modified). If you then keep it, the status changes to (kept). If you edit it again, its status becomes (modified) again.
If you don’t edit a file, but another user promotes a new version to the backing stream, your version becomes (stale). If you do edit such a file, its status becomes (overlap), indicating that two or more users have modified the same version concurrently.

The two main commands for determining the status of files are stat and files. Use the files command when you’re interested in a particular set of files:

accurev files Red.java White.java    (status of two files in the current directory)
accurev files \.\test    (status of all files in the “test” directory)

Use the stat command when you’re interested in a particular status. For example, this command lists all the files — throughout the entire workspace — that have (kept) status.

accurev stat -k

The output of the files and stat commands includes one or more status flags for each file:

\.\src\Red.java    cwheel_dvt_derek\12   (6\12)   (modified)   (member)
\.\src\White.java  cwheel_devel\6   (6\3)   (backed)
\.\src\Blue.java   cwheel\2  10\7)   modified)

(The information preceding the status flags are version-IDs.)

Getting Element History

AccuRev keeps track of the complete history of each version-controlled file (or element). Changes to the AccuRev repository are structured as a set of atomic transactions. The most common transactions for an element record keep and promote actions. Transactions are also logged in other situations: when an element is first added to the depot (recorded as create, even though the command-name is add), when you rename it or move it to a different directory (recorded as move), when you incorporate someone else’s changes into your work (recorded as merge), etc.

The hist command, in its simplest form, lists the complete transaction history of an element:

accurev hist White.java

There are many options, including listing a particular transaction:

accurev hist -t 43020 White.java

... or listing, say, just the dozen most recent transactions:

accurev hist -t now.12 White.java

You can also restrict the listing to transactions of a particular kind (say, keep transactions), transactions performed by a particular user, or transactions involving a particular stream.

Here are a couple of typical transactions, as listed by hist:

transaction 43020; move; 2009/10/28 14:34:44 ; user: derek
   dst : \.\src\White.java
   src : \.\src\W.java
   \.\src\W.java 6/6 (6/6)
   ancestor: (6/5)

transaction 43019; keep; 2009/10/28 14:27:40 ; user: derek
   # improve error message
   \.\src\W.java 6/5 (6/5)
   ancestor: (6/4)

Tracking Other Users’ Work

With AccuRev, the standard way to manage a group of users working on the same project is to have a dynamic stream for the project (termed the backing stream), along with a private workspace for each user. All the workspaces are based on (or “backed by”) the common backing stream. The wip command (“work in progress”) shows which files are under active development across the entire project, with a workspace-by-workspace breakdown.

> accurev wip -s brass_dvt
\.\tools\perl\findtags.pl
   brass_dvt_mary
\.\tools\perl\reporter.pl
    brass_dvt_mary
\.\doc\chap01.doc
   brass_dvt_john
\.\doc\chap04.doc
   brass_dvt_john
\.\doc\procfiles.py
   brass_dvt_john
\.\tools\perl\reporter.pl
   brass_dvt_john

Incorporating Other Users’ Work into Your Workspace

The set of users working on a particular project (or subproject) all have workspaces that use the same backing stream. Users make changes in their private workspaces, and preserve those private changes with keep commands. Then they make the changes public — that is, available to be incorporated into other users’ workspaces — with promote commands.

Other users’ work never appears in your workspace automatically. This could be destabilizing to your own work (no matter how good their code is!). Instead, you issue an update command when you decide to incorporate your colleagues’ recently promoted changes into your work. This brings into your workspace all “new” versions of elements — versions created since the workspace’s last update.

Note that the entire workspace is updated; you can’t restrict update to process a particular file or directory. This reflects AccuRev’s commitment to the best practice of having a workspace contain, as much as possible, a “matched set” of versions — not “old” versions of some elements and “new” versions of others.

Accordingly, the update command doesn’t accept any filename or directory-name arguments:

accurev update

You can update your workspace as often or as infrequently as you wish. You never have to worry about “clobbering” files that you’re currently working on — update skips over files that you have made “active” in your workspace with keep (or several other commands). It’s even careful not to overwrite files with changes that you haven’t yet preserved with keep.

If you need to update files that you’re currently working you, you may be able to use update –m to accomplish this. See Handling of (modified) Files / Merge on Update.

Concurrent Development — When Streams Collide

In a concurrent development environment, it’s inevitable that at some point, two or more users will work on the same file at the same time. That is, each user makes changes to a copy of the file in his private workspace. So the users are not literally modifying the same file, and there is no issue of users overwriting each other’s private changes.

But the “clobbering” issue does arise when the users want to make their changes public, by promoting their private versions of the same file to the shared backing stream. If you’ve made changes to a file in your workspace, and another user promotes a new version of that file to the backing stream, your file’s status becomes (overlap). You can continue working on the file as long as you wish, saving intermediate versions with keep. Before you promote your work to the backing stream, you must merge the backing-stream version with your version. This creates a version in your workspace that includes everyone’s work — no one’s changes get “clobbered”. You can then promote the merged version to the backing stream.

A typical invocation of the merge command is simple:

accurev merge Blue.java

This merges the file Blue.java in your workspace with the version currently in the backing stream. Often, you and your colleague(s) will modify different sections of the same file. In this case, the merge process is completely automatic, and you need only keep the merged file as a new version in your workspace:

Automatic merge of contents successful. No merge conflicts in contents.
Actions: keep, edit, merge, over, diff, diffb, skip, abort, help
action ? [keep]

If both versions being merged have a change to the same line, merge includes both changes, and you have to manually edit the results to resolve the conflict. For example, you and a colleague may have made conflicting changes to the same variable setting. That part of the merged file might look like this:

<<<<<<< Your_Version
    int retValue = -1;
 =======
    int retValue = ERROR_NO_COLOR;
>>>>>>> Backing_Version

merge puts in the separator lines and the “Your_Version” and “Backing_Version” annotations. You edit out all this extra text, leaving just the correct assignment of the retValue variable, say:

int retValue = ERROR_NO_COLOR;

When you’ve fixed all such conflicts, you keep the merged file as a new version in your workspace.

The preceding paragraphs describe AccuRev’s command-line merge algorithm. Alternatively, you can set an environment variable to have merge invoke a third-party merge program.