add

add a new element to a depot

Usage

accurev add [ -c <comment> ] [ -d ] [ -E <value(s)> ] [ -x ] [ -R ] [ -s ]
	[ -fi | -fI ] [ --ignore ] { -l <list-file> | <element-list> }

Description

The add command converts one or more existing files, directories, and/or links in a workspace to version-controlled elements. The new elements are placed in the depot associated with your workspace. (They cannot be moved later to another depot.) Version 1 of each element is created in your workspace stream. The new elements will not appear in other streams or workspaces until you promote them.

In the transaction recorded in the database for an add command, the AccuRev operation is listed as “create”, not “add”. Transactions are listed by the hist command.

If a pre-create-trig trigger is defined for the depot, it fires before the add command is executed. See mktrig and AccuRev Triggers in the AccuRev Admin Guide.

Controlling the Element Type and Exclusive File Locking State

By default, the add command sets the element type to binary if the file contains any null characters (0x00). If the file does not contain any null characters, it sets the element type to text.

Note: Based on this algorithm, Unicode files are usually considered to be binary, not text.

You can override add's element type determination with the -E option, specifying text, binary, or a third element type, ptext (a variant of text that is never assigned automatically). See below for a description of how AccuRev handles ptext elements. You can also set the new element’s exclusive file locking state: serial (exclusive file locking enabled) or parallel (exclusive file locking disabled).

By default, all files in a workspace are writable. You can edit any file at any time, and use keep to create new versions of them. But if you use the -E serial option, the file becomes read-only after you promote it to the backing stream. See File Locking in Workspaces.

You can change both the element type and exclusive file locking state in subsequent keep -E commands. This change affects the newly created version and future versions only; it does not change the type of any existing version.

To see an element’s type, use the hist -fv or stat -fk command. To see an element’s exclusive file locking state, use the stat -fx command (see the hierType attribute in the XML-format listing).

Using Triggers to Control the Element Type and Exclusive File Locking State

Setting of the element type or the exclusive file locking state (or both) can be automated with triggers. Settings made by triggers scripts override the add -E specifications, if any.

To set the element type based on file extensions and/or file content, set a pre-operation trigger with mktrig pre-create-trig. AccuRev ships with a sample trigger script, elem_type.pl. You can customize it to recognize new file suffixes.
To set the exclusive file locking state on a file-by-file basis, use the server-side pre-operation trigger, admin_preop_trig.

These triggers are fully described in AccuRev Triggers in the AccuRev Admin Guide.

How AccuRev Handles File Elements of Different Types

AccuRev handles binary files very simply: when a new binary version is created (with add or keep), AccuRev simply copies the file from your workspace tree to the repository, creating a storage file. When you retrieve a binary file from the repository (for example, with co -v or update), AccuRev simply copies the storage file to your workspace tree.

Handling of text files is more sophisticated. By default:

When a new version is created (add or keep), a new storage file is placed in the repository, with a single NL (or LF) character (hex character code x0A) at the end of each text line. This means that a version’s storage file may have different line terminators than the file you submitted to the add or keep command.
When a text file is copied into the workspace by an AccuRev command (e.g. update, pop), it gets the line terminators appropriate to the machine where the workspace is located: NL (x0A) for a UNIX/Linux machine, or CR-NL (x0D x0A) for a Windows machine.

On the individual element level, you can override the manipulation of line terminators by specifying the “preserve text line terminators” element type, with the -E ptext option. Files of this type are copied to and from the repository with no change, just like binary files.

On the workspace level, you can force the use of a particular line terminator when text files are copied to the workspace, using the -e option to mkws or chws. This applies to all elements of type text, but not to elements of type ptext.

How AccuRev Converts Existing Links to Link Elements

The add command converts existing link objects with (external) status to AccuRev elements as follows:

An existing hard link is always converted to an AccuRev file element.
An existing symbolic link (UNIX/Linux) or symlink/symlinkd/junction point (Windows) is converted to an AccuRev element-link element (elink) in these circumstances:

The target is a file element, directory element, or elink in your workspace, and you omit the -s command-line option. (If the target is an slink, you must use -s to convert the object to an slink. You cannot create an elink that points to an slink.)
An existing symbolic link (UNIX/Linux) or symlink/symlinkd/junction point (Windows) is converted to an AccuRev symbolic-link element (slink) in these circumstances:
- The target is an element in your workspace, and you specify the -s command-line option. (If the target is an slink, you must specify this option.)
- The target is an (external) object in your workspace, and you specify the -s command-line option.
- The target is a non-existent location within your workspace, and you specify the -s command-line option.
- The target is a location outside your workspace.

Controlling the UNIX/Linux Access Mode

On a UNIX/Linux machine, if a file has any of its executable bits (user, group, other) set, then add automatically sets all three bits on the kept version. Otherwise, all three bits are cleared on the kept version.

You can set or clear the executable bits on subsequent versions, using the accurev chmod command.

Adding Directories to the Depot

add can create directory elements as well as file elements. For each file it processes, add automatically creates elements (if necessary) for the file’s directory, its parent directory, and so on up to the top level of the depot. If you want to turn an empty directory into an element, you can specify it as a command-line argument, or you can let add -x find it automatically.

Options

–c <comment>	Specify a comment for the transaction. The next command-line argument should be a quoted string. Alternatively, the next argument can be in the form @<comment-file>, which uses the contents of text-file <comment-file> as the comment.
-d	Deny access to other users. If your site makes use of element-level security (“EACLs”), this option allows you to add elements to the depot and immediately make them inaccessible to other users, while assigning FULL access to the user adding the element. After adding the element, the adding user can then set the EACLs appropriately.
-E <value(s)>	Specify the element type: text (default) or ptext or binary; and/or specify the exclusive file locking state for this element: serial or parallel. To specify two (non-conflicting) values at once, separate them with a comma, but not a SPACE: -E serial,binary See Controlling the Element Type and Exclusive File Locking State (above).
-l <list-file>	Process the elements listed in <list-file>. This must be a text file, with one element name per line. Extra whitespace is not allowed; make sure there are no empty lines and no leading or trailing white space around the filenames. Wildcards are not expanded. There is no provision for comment lines in the file. If you use this option, any <element-list> specified is silently ignored.
<element-list>	One or more element names, separated by whitespace. If you also specify a <list-file> using the –l option, this <element-list> is silently ignored.
-R	Recurse into each directory specified in <element-list>, and add all the external files in that directory subtree. You need not specify the -x option. (Use “.” to specify the current working directory.)
-x	Select all external files and directories in the workspace, except objects that match any of the patterns specified by the .acignore file.
-fi	Select all files and directories, even if they are excluded by the value of the .acignore file. (See the -x description.)
-fI	Select only those files and directories specified by the value of the .acignore file.
--ignore	Specify a pattern of elements; external elements matching this pattern are ignored by the add command. The --ignore option can be used multiple times for the same command, but each instance can specify only one pattern. For example: `accurev add -x --ignore=".obj" --ignore=".txt" --ignore="!file1.txt"` Can also be used to specify the pathname of a text file that contains one or more patterns. For example: `accurev add -x --ignore="@c:\work\my_ignore.txt"` Note that the patterns expressed using the --ignore option take precedence over patterns expressed using the .acignore file.
-s	Forces all symbolic link objects (at the OS level) whose targets are within the current workspace to be converted to slink elements (at the AccuRev level). See How AccuRev Converts Existing Links to Link Elements.

Examples

Create element foo.c:

> accurev add foo.c

Create binary element fig1.jpg:

> accurev add -E binary fig1.jpg

Create elements from all files in the workspace that are not already under version control:

> accurev add -x

Create directory elements from three new directories:

> mkdir sun linux windows > accurev add sun linux windows

Create elements from all files in subdirectory widgets that are not already under version control:

> accurev add -x -R widgets

add