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.
|
|
•
|
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:
|
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.
|
C:\dvt_work (Windows)
C:\ac_workspaces\brass_dvt
H:\Projects\Colorwheel\mary
/usr/projects/mary/brass_dvt
(UNIX/Linux)
/workspaces/ColorWheel/mary
|
•
|
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.
|
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.
(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:
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.
If you’re in a workspace in which you must “check out” a file before editing it (see File Locking in Workspaces), version-controlled files are maintained in a read-only state until you invoke the
co or
anchor command on them.
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.
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:
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:
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:
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:
Using an environment variable, you can configure diff to use a third-party file-difference program.
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.
As with keep, you can specify particular files to promote on the command line or place their names 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:
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).
|
•
|
Determine the past statuses — that is, the development history — of one or more elements.
|
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:
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:
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.
The output of the files and
stat commands includes one or more status flags for each file:
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:
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.
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
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:
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.
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.
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:
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:
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:
When you’ve fixed all such conflicts, you keep the merged file as a new version in your workspace.