DVS(1)

NAME
dvs - checks in/out and manages artifacts with NUCM

SYNOPSIS
dvs <command> [ options ] [ path ... ]

DESCRIPTION
dvs manages distributed versioned files and collections of files adopting a check-in/check-out policy with locks. All dvs functions operate on a list of artifacts and some of them accept some additional parameters. An artifact can be either an atom or a collection of other artifacts. In all the check-in/check-out operations, atoms correspond to files while collections correspond to directories in the local workspace, i.e., the local file system. The artifacts managed by dvs are stored in one or more NUCM databases. Thanks to the NUCM primitives, dvs transparently manages the connections to the various databases and the distribution of artifacts. dvs can establish connections through TCP proxies such as SSH (http://www.ssh.fi) that provide secure communications and interoperability through firewalls.

PATHS
A path for dvs is a string that identifies an artifact. Paths are an extension of usual file system paths that can also incorporate the server address and version numbers. The general form of a path is:

[//hostname[:port#]/]artifact[:version#][/artifact[:version#]...]

Here are some examples:
     foo.c
     inc/bar.h
     inc
     test.c:3
     inc:4/new.h
     //host.xyz.edu:1234/nucm_root
     //machine.hjk.com/nucm_root:4/main.tex Paths that don't refer to a NUCM server correspond to files in the file system that have been created as a consequence of a check-out operation. Such paths are always relative to the current working directory. So the path foo.c will refer to the file foo.c in the current working directory. Artifact names must not begin with a dot (`.').

DEFAULT SERVER
For all the operations that require to connect to a NUCM server, dvs uses either the server that is specified in each path (see PATHS) or the default server. The hostname for the default server is specified by the NUCMHOST environment variable. If NUCMHOST is not defined, localhost is used. The port number is specified by the NUCMPORT variable the default value being 1234.

DVS COMMANDS
There are thirteen basic commands. They are co (check-out), ci (check-in), close, link, unlink, lock, unlock, list, log (print versions log), setlog, printlocks, whatsnew, and sync.

co [-R] [-l] [-f] [-last] [-here] path [path...]
    check out artifacts. co checks out path from the NUCM repository. If path is not a valid local path or if -here is specified then path is checked out into the current working directory, otherwise path itself is used as a target. If path is an atom, the corresponding file is created. If path is a collection then a directory is created. If path is a collection and the -R option is specified, then every element of path is recursively checked-out. If the -l option is specified, dvs tries to lock path and prepares it for change. If -l is specified on a collection together with -R, only that collection is locked while all its components are checked out read-only. If the a version of path other than the one determined by path is already present in the workspace, co prints a warning message and prompts for closing it. The -f option forces dvs to close all the artifacts that conflict with the check out operations. When trying to resolve a path for check-out, dvs automatically determines the version number in case it is not already specified in the path. The following criteria apply: if the current working directory corresponds to a collection that contains path, the version referred by that collection is checked out. If the current working directory does not correspond to any collection or if it corresponds to a collection that does not contain path, then the last version of path is checked-out. If the -last option is specified, the last version is checked out regardless of the content of the current collection. If -last is specified together with -R, then the -last flag is applied recursively to all the artifacts that are checked out. In all the check-out operations, if path can not be resolved and if it does not contain a reference to a NUCM server, dvs automatically looks up the default server.

ci [-R] [-l] [-m message] path [path ...]
    check-in artifacts. ci checks in each path in the database. ci has two slightly different semantics depending on the fact that path is already linked to the current working collection or not. If path is already referenced in the current directory, a new version is created and checked in, provided that the current version is locked. If path is not already linked to the current working collection, dvs creates a new artifact in the database and adds it to the current version of its collection (i.e., the directory where the artifacts stands in the workspace). To do so, such a collection must exist and it must be locked. The initial version number of an artifact is 1. Only in this case, if the -R option is specified and path is a directory, all the sub-tree of files in path is recursively checked in. Note that checking in the first version or a new version of an artifact does not imply a check in of the collection (or collections) that refers to the previous version of that artifact. Collections have to be explicitly checked in. Checking in a directory (i.e., a collection) causes that collection to be updated with all the version that are currently present in the file system. Checking in a collection also requires that collection to be locked. In any case, for every artifact that is checked in, dvs prompts for a log message to be attached to the new version. If the -m option is specified, message is used as a log message for every check-in operations. If the -l option is specified, the new version is immediately locked. After a check-in is completed, the previous version is automatically unlocked. Note that if the artifact is new, then the collection that contains it is not automatically checked in and unlocked.

close [-f] path [path ...]
    closes each path. Closing a path means removing the file or the directory and all its content from the local workspace. close fails whenever path or an artifact contained in path has been checked out with lock. Also, in case path is a directory, dvs checks for the presence of other non-dvs files in that directory, and, in case, it prompts the user for a confirmation before proceeding to remove them. In these cases, the -f option can be used to force dvs to close path anyway. Note that close has no effect on the database, i.e., it does not commit changes to the NUCM database nor it unlocks artifacts.

link [-last] path [path ...]
    links each path to the current collection, i.e., it makes path a member of the current collection. If path doesn't refer to an artifact that exists in the workspace or if the -last option is specified, the latest version is linked. Otherwise, the version referred in the workspace is linked. link is an operation that affects the current collection, thus, the current collection must be locked. Similarly to ci, link does not implicitly check in the current collection. path must be an existing artifact.

unlink [-f] path [path ...]
    removes path from the current collection. Similarly to link, unlink requires the current collection to be locked. path is not actually deleted from the database as long as there exist at least one version of a collection that refers to any version of path. unlink has the same effect of close on the workspace, i.e., unlink removes path from the workspace unless some path or any artifact contained in path has been checked out for change. If path is a collection, dvs also checks that path does not contain any other non-dvs files that would be removed together with path. In both these cases, -f forces the execution of the command.

lock [-last] path [path ...]
    locks each path and prepares it for change. The locks are assigned on a per version basis, i.e., two users can lock two different versions of the same artifact at the same time. lock fails when path is already locked by another user. If path does not specify a version, the version referred in the workspace is locked. If the -last option is specified then the latest version of path is locked, regardless of the version specified in path or the one referred in the workspace. After setting the lock information, path is prepared for change, i.e., it is made user-writable. lock fails if path is not open in the workspace. Locks are based on the identity of the user that executes dvs. By default, the login name is used, however, if the USERADDRESS environment variable is set (e.g., to the e-mail address), its value is used to mark locks instead of the login name. This variable is provided in case the login name is not adequate. For example, when one user has different login names on different machines or when two different users can have the same login name. Note that dvs can not control the authenticity of USERADDRESS.

unlock [-last] [-f] path [path ...]
    removes the lock from path and reverts changes restoring the version of path that was previously in the workspace. unlock fails if path is locked by another user or if path is not open in the workspace. Similarly to lock, unlock determines the version from path if it is explicitly specified or from the current collection or it uses the latest if the -last option is specified. In restoring the previous version, dvs closes the artifact that is currently in the workspace, thus, similarly to close, unlock fails whenever path or an artifact contained in path has been checked out with lock. Also, in case path is a directory, dvs checks for the existance of other non-dvs files in that directory, and, in case, it prompts the user for a confirmation before proceeding to remove them. In these cases, the -f option can be used to force dvs to close path anyway.

list [-v] [-o filter] path [path ...]
    lists the contents of path. list fails if path is not a collection. By default, list produces a list of artifact names, but if -v is specified, dvs outputs a verbose list containing version information. Here is an example of a verbose output:
         % dvs list -v .
         ! A.bod v.3 3 (2)
           B.bod v.1 1 (1)
         - figure.eps - (4)
           paper.tex v.9 9 (9)
         + paper.bib v.2 2 (-)
         * paper.ps                            -  (-)
    The first number on the right side is the version that is currently in the workspace (path). The number in parentheses is the version that is referenced in the collection (path). Files marked with `-' are those that are referenced in the collection, but are not present in the workspace; `+' indicates that the artifact is in the workspace, but it is not referenced in the collection; `*' marks non-dvs files, and `!' says that the version in the workspace doesn't match the one in the collection. By default, all these artifacts are listed, however a filter (-o flag) can be used to list just one or more of these classes. In particular, filter is a string of one or more of the following characters:

    c   (collection) artifacts that are members of path;

    w   (workspace) artifacts managed by dvs that are in the workspace;

    b   (both) artifacts managed by dvs that are members of the collection defined by path and that have been checked out into the workspace;

    o   (other) files that don't correspond to artifacts managed by dvs.
For example:
     % dvs list -v -o wo

log [-n num]path [path ...]
    prints the log of the versions of path. The log reports the list of versions for each path path. For each version, the creation date, the author, lock information, and the log message are displayed. dvs prints the log for all the versions of path in reverse order, i.e., from the latest version (highest version number) to the first version. -n can be used to limit the log output to the num most recent versions.

setlog [-m message] path [path ...]
    sets the log message for each path. If the -m option is specified, message is used as a log message for every path. Otherwise dvs prompts for a log message for every path.

printlocks [-R] [-v] path [path ...]
    prints the lock information for all the versions of path that are locked. If path is a collection and the -R option is specified, path is recursively checked for locks. By default, this command outputs only paths that have at least one locked version. The -v option can be used to produce a more verbose output with all the versions that are locked and the name of the users that hold the locks.

whatsnew [-R] [-v] path [path ...]
    prints out path if the version referenced in the workspace does not correspond to the latest version checked-in in the repository. If path is a collection and the -R option is specified, then all the components of path is recursively scanned for new versions. The -v option causes dvs to print out the current version and the latest version for each path.

sync [-R] [-f] path [path ...]
    this command is useful to refresh the workspace with the latest versions of the artifacts. sync checks whether the version of path in the workspace is actually the latest version of path in the repository. In case the workspace contains an earlier version, dvs checks out the latest version. With -R, if path is a collection/directory, dvs scans path recursively refreshing all its components. The effect of refreshing an artifact is identical to a `co -last', thus, sync uses the -f flag to force the check-out operation, in case it would overwrite other versions already checked out for changes or that would remove other non-dvs files.

SECURITY AND FIREWALLS
It is possible to encrypt dvs connections and/or to use dvs through firewalls by means of some external TCP/IP proxy/forwarding mechanism such as SSH (http://www.ssh.fi). dvs is completely independent from the authentication procedure and the encrypting algorithms possibly adopted by the forwarding mechanism. The proxy maps addresses---host and port---of NUCM servers into proxy addresses---host (usually localhost) and port. For example, using SSH:

ssh -L 4321:serl.cs.colorado.edu:1234 host

creates a local proxy on port 4321 (localhost) for a server running on serl.cs.colorado.edu on port 1234. Any connection made to localhost:4321 is forwarded to serl.cs.colorado.edu:1234. Once a set of proxies is set up, dvs needs to know whether or not it needs to use a proxy and which one to contact a server. In practice, dvs needs to know which proxy maps to which NUCM server. This information is provided to dvs through a proxy-map file that is specified through the DVS_PROXY_MAP environment variable. The proxy-map file is a text file, read line by line. A line beginning with a poind sign ('#') is considered a comment. Empty lines are permitted as well. Other lines define a mapping in the form:

<server_host>:<server_port> <proxy_host>:<proxy_port>

Here is an example of a valid proxy-map file:
     #
     # sample proxy-map file
     #

     #
     # this first line corresponds to the example above
     #
     serl.cs.colorado.edu:1234    localhost:4321
     #
     123.123.123.123:1969    localhost:1969
     #
     # both IP numbers and host.domain names are valid
     # Once the proxy-map has been created and DVS_PROXY_MAP has been set to point to it, you can use dvs as usual and all the connections to servers listed in the proxy map will go throug the appropriate proxy.

FILES
dvs creates two additional files in every directory it operates. They are .workspace and .collection. The user should never modify or remove these files.

ENVIRONMENT

NUCMHOST
    the name of the default NUCM server.

NUCMPORT
    the port number of the default NUCM server.

USERADDRESS
    the id that is used to lock artifacts.

DVS_PROXY_MAP
    the pathname of a proxy map file

EXIT STATUS
The exist status of dvs is zero if and only if the operation defined by the command terminates successfully for every path.

DIAGNOSTICS
During its operations, dvs prints some minimal progress report and some error message in case something goes wrong. The error messages communicate the dvs error condition and possibly the low-level error that caused it. The low-level errors are printed out in parentheses.

KNOWN BUGS AND LIMITATIONS
Artifact names must not begin with a dot (`.'). Some operations can not be applied to the current working directory, for example, dvs would not allow `dvs close .'. The user identity stored in USERADDRESS must not exceed 256 characters. The autenticity of USERADDRESS is by no means checked by dvs. It is possible that some NUCM function returns a failure without specifying which kind of error occurred. This is usually due to some file I/O problem (e.g., wrong permissions). In those cases, dvs fails printing out a dvs-specific error message and "unknown error" as a low-level error specification. Some critical condition are not yet properly handled. For example, if dvs is interrupted (e.g., because of a user signal), the database and the local workspace may not be in a consistent state. To restore an artifact in a consistent state, it is usually sufficient to close and re-open it in the local workspace or to use unlock. There is one case in which dvs can not recover from an inconsistent workspace without external intervention. This situation arises when an artifact is removed from the workspace without using `dvs close' (e.g., using /bin/rm). To recover to a consistent state, simply `touch' the file or create the directory that has been removed and then use `dvs close' to remove it again. dvs can not sync or check-out different versions of artifacts that are in the workspace but not in the current collection (e.g., if you `dvs co nucm_root:3/project`, then `project' will exist in the workspace, but not in any collection). These ``top-level'' artifacts must be checked out with (one of) their absolute paths (i.e., those that refer to a NUCM server). So, for example, having a `project' artifact in the workspace and knowing that (one of) its absolute address is `//serl:1234/nucm_root:3/project', you can sync project with:
     dvs co -last //serl:1234/nucm_root:3/project

SEE ALSO
nucmserver(1), nucmclient(1), createrepository(1), removerepository(1), ci(1), co(1), rcs(1), rlog(1), http://www.cs.colorado.edu/~carzanig/dvs

AUTHOR
Antonio Carzaniga - carzanig@cs.colorado.edu Copyright (c) 1997-1999 Software Engineering Research Laboratory, Department of Computer Science, University of Colorado at Boulder. All rights reserved.