mkws

create a new user workspace

Usage

accurev mkws -w <workspace-name> -b <backing-stream> -l <location>
	[ -k <kind> ] [ -e <eol-type> ] [ -i ]

Description

The mkws command creates a workspace, in which you can work with the version-controlled files (elements) in a particular AccuRev depot. See Entity Names for information on naming workspaces.

A workspace consists of two parts:

• Workspace tree: a directory tree located in your machine’s disk storage, or in remote storage accessed through a network file system. The directory tree is simply a collection of files that is (loosely speaking) your copy of the depot.
• Workspace stream: a stream in the designated depot, dedicated to the workspace. All changes you make in the workspace are initially recorded in this “private” stream.

You use accurev commands to move development data between the workspace tree (temporary private storage) and the depot (permanent public storage):

• The pop (“populate”) and update commands copy files from the depot to the workspace tree. Each file is a copy of a particular version of some element.
• The keep command copies files from the workspace tree to the depot. Each copied file becomes a new version of the element, in the workspace stream. The creation of the new version is recorded as a transaction in the database.

When you create a workspace, you assign it a simple workspace name. The associated workspace stream is assigned the same name, because it is dedicated to the workspace. This name must be unique across all depots; mkws helps you out in this regard by automatically appending your principal-name to the name you specify with the -w option.

Initial Update Level

Each workspace has an update level, which indicates how up-to-date the workspace’s files are. For example, an update level of 3475 indicates that your workspace has incorporated (through the update command) changes recorded in transactions up to and including transaction #3475.

When you create a workspace, mkws does not copy any files into the workspace tree. The workspace’s update level is initially set to transaction #0. Since no version of any element existed at this update level (before any transactions were recorded in this depot), there is no data to be copied into the workspace. The -i option (see below) provides a variant of this workspace initialization scheme.

To fill a new workspace with files, enter an update command. This creates a directory hierarchy in the workspace tree and sets the update level to the depot’s most recent transaction.

Location of the Workspace Tree in the File System

You can create a workspace tree anywhere in the client machine’s file system — subject to operating-system access controls. But don’t create a workspace within the AccuRev installation area: typically, C:\Program Files\AccuRev (Windows) or /opt/accurev (UNIX/Linux).

You can also create a workspace on a remote machine’s disk, as long as that location is accessible on your machine through the operating system’s remote-file-access capability (“sharing” on Windows systems, “mounting” on UNIX/Linux systems). Again, access control imposed by the network file system may restrict where you can create a workspace.

Workspace Options

By default, mkws creates a standard workspace, which has the following characteristics:

• It contains all available elements. That is, the workspace contains a version of every element in the workspace’s backing stream. (You must follow the mkws command with an update command to perform an initial load of these versions into the workspace tree.)

  After creating the workspace, you can control exactly which elements appear in it, using the include/exclude facility. This facility is implemented through the commands incl, incldo, excl, clear, and lsrules. (You don’t have to specify any mkws option to enable the include/exclude facility. It’s always enabled for all workspaces.)

• The version-controlled files in the workspace tree are writable at any time. There is no need to perform a checkout operation on a file before beginning to work on it.

  You can override this characteristic in either of these ways: having the workspace use the exclusive file locking feature (-ke option), or having the workspace use the anchor required feature (-ka). These features are similar: they both require you to checkout a file, using the anchor or co command, before modifying it. Exclusive file locking goes further, preventing multiple users from working on the same file at the same time. See Serial Development through Exclusive File Locking in the AccuRev Concepts Guide.

  An exclusive file locking workspace cannot subsequently be changed with the chws command. This restriction also applies to a workspace that was not itself created with the -ke option, but whose depot does use the exclusive file locking feature.

• Version-controlled text files in the workspace tree use the line terminator appropriate for your machine’s operating system: NL for UNIX/Linux, CR-LF for Windows.

  You can override this characteristic with the -e option: -eu forces the workspace’s version-controlled text files to use the UNIX/Linux line terminator; -ew forces the workspace’s version-controlled text files to use the Windows line terminator.

Workspace Flexibility and Persistence

The naming scheme separates a workspace’s logical name from its physical location in the file system. This makes it easy to move a workspace to a larger disk, to a faster machine, to a disk farm, etc. You must use the chws command to inform AccuRev of such a location change.

If you create a workspace by mistake, you can make it invisible with the rmws command. This does not actually delete the workspace — that would violate AccuRev’s TimeSafe property. Once created, a workspace persists in the workspace registry forever. rmws merely hides the workspace, and attempts to create another workspace with the same name will fail.

Converting an Existing Directory Tree into a Workspace

The location you specify with the -l option can be an existing directory. This has the effect of turning the entire directory tree at that location into a new workspace. All the files and subdirectories in the directory tree start out as external objects. To convert them all to version-controlled file and directory elements, execute the command accurev add -x from anywhere within the newly created workspace.

Be careful to avoid the mistake of trying to “convert the same tree twice”. For example, here's an incorrect usage scenario:

1. In the pre-AccuRev era, John and Mary each made a copy of the organization's “official” source tree. They each started to modify a few files within their personal copy of the tree.
2. The organization adopts AccuRev, and John and Mary install the software on their machines.
3. John converts his copy of the source tree to a workspace.
4. Mary converts her copy of the source tree to a workspace.

Everything seems OK, but name collisions will occur when both John and Mary promote versions of their newly created file elements to the common backing stream. For example, Mary might promote her version of file lib/gizmo.h to the backing stream first. When John subsequently attempts to promote his version of lib/gizmo.h to the same backing stream, AccuRev will complain “Name already exists in backing stream”.

What's the correct procedure? Only one person should create AccuRev elements from an existing source tree. If John has already performed step #3, they should proceed as follows:

1. John promotes all his newly created elements to the common backing stream, using the command accurev promote -d.
2. Mary creates a new, empty workspace with mkws, and uses the update command to load John's versions into her workspace.
3. Mary selectively copies the files that she modified from her copy of the original source tree to her new workspace. She updates the timestamps on these file with accurev touch.

Options

-w <workspace-name>	Specify a name for the new workspace. The name may begin with a digit (provided there is at least one non-digit in the name), must not begin with a dot (.), must not include either a slash (/) or a backslash (\) and must not be a name of digits only. mkws adds the suffix _<principal-name> to the name you specify (if you don’t include the suffix yourself).
-k <kind>	Specify the kind of workspace to be created. -kd: (“default”) Create a workspace that doesn’t have any of the features enabled by the other -k options. -ke: Create a workspace in which an exclusive file lock is placed on a file when you begin active development on it. See Serial Development through Exclusive File Locking in the AccuRev Concepts Guide. -ka: Create an anchor-required workspace, in which you must use the anchor or co command on a file before modifying it. The -ke and -ka options are mutually exclusive. See the incl and excl reference pages for a way to configure a workspace with just the files you need. Also, see the -i option below.
-b <backing-stream>	Specify the stream to be the backing stream of the workspace.
-l <location>	Specify the full pathname where the workspace is to be created.
-e <eol-type>	Specify the line terminator to be used when an AccuRev command (e.g. update, co) copies a version of a text file from depot storage to the workspace. (In depot storage, all text files are stored with the AccuRev-standard line terminator, NL.) The <eol-type> can be d (default: use the standard line terminator for the client machine’s operating system), u (use the UNIX/Linux line terminator, NL), or w (use the Windows line terminator, CR-NL).
-i	Configure the workspace to be empty initially, by implicitly executing the command incldo on the top-level directory of the depot. The new workspace is also updated to the depot’s most recent transaction.

Examples

Create a workspace for bug fixes in /home/jsmith/ws, backed by the gizmo1.1 stream:

> accurev mkws -w gizmo_bugfix -b gizmo1.1 -l /home/jsmith/ws/test

This creates a workspace and a stream named gizmo_bugfix_john_smith. (if your principal name is john_smith).

See Also

excl, incl, mkref, show (streams), start