@node Command Reference
@chapter Command Reference
@cindex Command Reference

@itemize @bullet
@item
@command{add file} @cmdarg{file} ...

Adds one or more files to an existing branch.

User's Workspace specifies the current (working) line of development
into which the specified files will go.  The specified files are the
actual local filenames of the files to be added.  Permanent changes
don't take effect until the execution of the @cmdref{commit} command.

@item
@command{add member} @cmdarg{group} @cmdarg{member}

Adds @cmdarg{member} to the specified (existing) @cmdarg{group}.  The
specified @cmdarg{member} must either be a user or group and you must
have write access on the group in order to add members to it.

@item
@command{adduser} @cmdarg{cert-file} @cmdarg{('r'|'w'|'rw')}

Registers a user on a repository by copying the new user's certificate
file (whose path is specified as @cmdarg{cert-file}) to the repository
and granting him the specified access (read, write, or read-write).
Currently, only X.509 certificates in PEM format are accepted and the
certficate MUST have a valid email address for the user.  All new users
are added to a special group called @dfn{everyone}, to which all
repository users have read access.  Users can be referenced via the
email address in their certificate.  Only users in the administrative
group may perform this command.

@item
@command{bind} @cmdarg{key} @cmdarg{value}

Adds an entry in the user's directory that maps @cmdarg{key} to @cmdarg{value}.
In most cases @cmdarg{value} is the OpenCM URI of an archived object and
@cmdarg{key} is the human-readable name associated with that object.

@item
@command{checkout} @cmdarg{branch-spec}

Checks out all objects in the specified line of development (branch)
to the user's local filesystem and creates an associated Workspace
corresponding to that line of development. File modification times are
set to the modification time that existed at the time of checkin. The
branch must be specified either by an entry in the user's OpenCM
directory or as an absolute OpenCM URI.  In either case, a specific
version is specified by appending a forward slash followed by a
version number to the end of the specification.  If no version is
specified, the latest (most recent) version of the branch is used.

@item
@command{commit} [ @cmdarg{fsname} ...]

Uploads any local changes to the repository.  User's Workspace must
represent the latest repository configuration for that line of
development. Any conditionally added or deleted files (as a result of
@cmdref{merge} and/or @cmdref{update}) in the Workspace must be resolved
prior to committing.  If specific files are specified, only those files
are committed.

@item
@command{create branch} @cmdarg{branch-spec} @cmdarg{new-branch-name}

Creates a new line of development (branch) from an existing branch.
(Think of this as 'forking' an existing branch.) @cmdarg{branch-spec}
must specify a branch (or specific branch version), either as a URI, or
as an entry in the user's directory.  This command does not alter the
current Workspace.  Thus, a user must @cmdref{checkout} the new branch
in order to continue development with respect to that branch.  A
specific version is specified by appending a forward slash followed by a
version number to the end of the branch specification.  If no version is
specified, the latest (most recent) version of the branch is used.

@item
@command{create group} @cmdarg{new-group-name}

Creates a new group for use as an access control list and add an entry
in the user's directory that binds @cmdarg{new-group-name} to the newly created
group.  By default, the user is set as both the read and modify ACL entries
for the new group and is added as the first member.


@item
@command{create project} @cmdarg{new-name}

Creates a new empty branch and binds @cmdarg{new-name} to the new empty
branch in the user's directory.  The new branch can be populated by
checking it out via the @cmdref{checkout} command and executing
@cmdref{add file} and @cmdref{commit} when local files are available.


@item
@command{create repository} @cmdarg{local-path} @cmdarg{('fs'|'rcs'|'sxd')} @cmdarg{admin-user}

Creates a new repository. User must specify the absolute path of the
repository, via @cmdarg{local-path}.  The first (admin) user of the
repository is specified via @cmdarg{admin-user}, which must be the local
path to a PEM file representing the admin user's X.509 certificate.
There are currently three supported file repository types: @cmdarg{fs}
which specifies a generic file system based storage scheme with no
compression, @cmdarg{rcs} which specifies a file system based storage
scheme using RCS for compression, and @cmdarg{sxd} which uses a
derivative of the Xdelta compression algorithm.  This command creates
the local directory @cmdarg{local-path} and populates it with all the
necessary metadata for a repository.  It also generates a private/public
key pair for the repository itself.  The user is prompted for
descriptive items for the keys.


@item
@command{create user} @cmdarg{user-spec}

Generates a passphrase-protected private key for a new user and then
generates a self-signed X.509 certificate based on that private key.
The @cmdarg{user-spec} defines the filename (without suffix) used for
naming the resulting private key and certificate files.  The files are
generated in the user's @file{users} subdirectory of their opencm
configuration directory.  Private key files have @file{.key} suffix and
certificate files have a @file{.pem} suffix.  By default, the opencm
configuration directory is @file{$HOME/.opencm}.  Safeguard all private
keys!  Those are the ones ending in suffix @file{.key}.  Individual users
should execute this command and then pass a copy of their certificate file
to the repository administrator for registration.


@item
@command{diff} [ @cmdarg{fsname} ... ]

Lists any differences between specified files in the user's Workspace
and the corresponding files on the repository.  If no @cmdarg{fsname}s
are specified all files are tested.

@item
@command{import} @cmdarg{new-name}

Creates a new branch and marks all files in the working directory for
upload to the repository.  This is equivalent to executing
@cmdref{create project}, @cmdref{checkout}, and @cmdref{add file}
sequentially, although this command automatically marks all local files
(and recursively all files within subdirectories).  A new entry is made
in user's OpenCM directory, binding @cmdarg{new-name} to the newly
created branch.  Actual file uploads don't occur until the execution of
the @cmdref{commit} command.


@item
@command{ls} [ @cmdarg{repos-path} ]

Displays listing of the specified OpenCM repository object. If no
repository path is specified, the user's ``home'' directory on the
repository is listed.

@item
@command{log} [ @cmdarg{filename}|@cmdarg{configname} ]

Displays commit history for a file or configuration. If a filename is
specified, it may be either a workspace file or a path to a filename
within a repository configuration. History for a file shows only those
messages corresponding to a commit where the file was changed.  If no
argument is given, this command displays commit information for every
configuration in the line of development associated with the user's
Workspace.

@item
@command{merge} @cmdarg{branch-name}

Merges the line of development (branch) specified by
@cmdarg{branch-name} into the user's local Workspace. The specified
branch and the one represented by the current Workspace must have a
common ancestor. (This means they must have both been derived from one
common configuration.)  Necessary mods are made only to user's Workspace
files.  Any conflicting merges are identified just as the 'diff3'
command would.  Permanent changes don't take effect until the execution
of the @cmdarg{commit} command.


@item
@command{mkdir} @cmdarg{subdir-path}

Creates a new subdirectory in the user's OpenCM directory.  You may
specify leading subdirs in @cmdarg{subdir-path} but any and all leading
subdirs must already exist in user's directory space.

@item
@command{mv} @cmdarg{old-fsname} @cmdarg{new-fsname}

Changes the local filename for a Workspace object from
@cmdarg{old-fsname} to @cmdarg{new-fsname}.  User must use this command
as opposed to a command-shell rename so repository will be able to track
the rename operation.  Permanent changes only take effect after
executing a subsequent @cmdref{commit}. Subdirs may be specified.


@item
@command{note}

Prompts user for new text to add to a running list of notes.  The
running list is maintained until the execution of the @cmdref{commit}
command.


@item
@command{notes}

Displays the user's current list of notes.


@item
@command{rebind} @cmdarg{oldkey} @cmdarg{newkey}

Renames @cmdarg{oldkey} to @cmdarg{newkey} for a current entry in the
user's directory.  Any leading subdirs in @cmdarg{newkey} must already
exist in user's directory space.

@item
@command{remove file} @cmdarg{file} ...

Marks one or more files in the user's Workspace to be deleted
permanently from the line of development.  Files are physically deleted
after subsequent execution of @cmdref{commit}.  To undo any changes
before committing, use the @cmdarg{revert} command.


@item
@command{remove member} @cmdarg{group-spec} @cmdarg{member}

Removes specified @cmdarg{member} from the existing group @cmdarg{group-spec}. 


@item
@command{revert} 

Reverses all modifications to a user's Workspace that were made since
the last @cmdref{commit}.  File modification times are reset to the
modification time that existed at the time of checkin. This can have
unexpected consequences for @kbd{make}, so a @kbd{make clean} (or
equivalent) is advisable after performing this comment.

@item
@command{rm} @cmdarg{file} ...

Marks one or more files in the user's Workspace to be deleted
permanently from the line of development.  Files are physically deleted
after subsequent execution of @cmdref{commit}.  To undo any changes
before committing, use the @cmdarg{revert} command. (This is an alias
to the @command{remove file} command.)

@item
@command{server} @cmdarg{repos-URI}

Invokes an instance of the OpenCM server.  The repository the server
manages must exist and is specified via @cmdarg{repos-URI}.  The
@cmdarg{repos-URI} must begin with @kbd{file://} and must specify the
full local path to the OpenCM repository.  If server is to run on the
non-standard port, then @cmdarg{repos-URI} must begin with
@kbd{file://localhost:port/} or @kbd{file://127.0.0.1:port/} where
@kbd{port} is replaced with the actual port number on which the server
should listen for incoming requests. 

@item
@command{set description} @cmdarg{mutable}

Prompts user for the new, full text description of
the specified object.  The @cmdarg{mutable} may be specified either
as an entry in user's OpenCM directory, or as an absolute OpenCM
URI.

@item
@command{set group} @cmdarg{mutable} @cmdarg{acl} @cmdarg{('r'|'w'|'rw')}

Sets the read and/or write ACL for a mutable object.  The
@cmdarg{mutable} is specified either as an entry in the user's OpenCM
directory or as an absolute OpenCM URI and user must have write access
to it.  The @cmdarg{acl} is specified similarly and must either be a
user or a group.  The final parameter specifies whether @cmdarg{acl}
is to be set as the read ACL, write ACL, or both.

@item
@command{set name} @cmdarg{mutable} 

Prompts user for new name (one-line synopsis) for specified
mutable.  The @cmdarg{mutable} must be specified either as an entry
in user's OpenCM directory or as an absolute OpenCM URI.

@item
@command{set user} @cmdarg{user} @cmdarg{('r'|'w'|'d'|'rw')}

Sets the repository read and/or write permissions for a user. Only admin
users may execute this command.  The @cmdarg{user} must be specified
either as an entry in executing user's OpenCM directory or as an
absolute OpenCM URI.  The final parameter specifies read ('r'), write
('w'), read-write ('rw') or revoked ('d') access.  Note that this
setting is for the repository as a whole.  Each archived object specifies
its own read and write access list.  A user must have at least read
access on the repository and not currently be revoked in order to connect
to that repository.

@item
@command{status}

Checks whether any local files in user's Workspace have been modified or
deleted since the last 'commit'. If no files have changed, nothing will
be displayed (unless the verbose command line option is used.)  The
@cmdref{commit} command makes all changes identified by 'status'
permanent in the repository.


@item
@command{tag} @cmdarg{branch-spec} @cmdarg{tag-name}

Identifies the line of development @cmdarg{branch-spec} by the unique
directory name @cmdarg{tag-name}.  @cmdarg{tag-name} is added to user's
OpenCM directory.  Only branches may be tagged and tagged branches are
read-only.  A branch must be specified either by an entry in the user's
OpenCM directory or as an absolute OpenCM URI.  In either case, a
specific version of the branch is specified (if needed) by appending a
forward slash followed by a version number to the end of the branch
specification.  If no version is specified, the latest (most recent)
version of the branch is tagged.

@item
@command{unbind} @cmdarg{key}

Removes the entry in the user's directory identified by @cmdarg{key}.
Leading subdirs may be specified in @cmdarg{key} but only the individual
entry specified by @cmdarg{key} is removed.

@item
@command{update}

Updates Workspace files whose contents do not match what's in the latest
configuration on the repository. Adds/removes local files accordingly as well.
Nothing is done if the configuration in the Workspace is newer than the
latest configuration in the repository.  When files are added or removed
from the Workspace, it's done conditionally.  User must specifically use
the @cmdref{add file} or @cmdref{remove file} commands to accept the
conditional changes.


@item
@command{version}

Displays the version of the OpenCM client that was executed.  If
connected to a repository, the version of the OpenCM repository is
also displayed.

@item
@command{whoami}

Displays the email address and expiration date from the user's
certificate file.  The actual certificate file used for any client
command can be specified by an environment variable, by a command line
parameter, or by the contents of @file{$HOME/.opencm/default.pem}.
Furthermore, it's common for OpenCM users (especially administrators) to
possess more than one certificate for OpenCM use.  This command is
useful for identifying the actual certificate presented to the client
program.

@end itemize
