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 that provide secure communications and interoperability through firewalls.
[//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 refers to the file foo.c in
the current working directory.
Artifact names must not begin with a dot (.), although a single dot can be used to refer to the current working directory (collection).
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, 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 has two slightly different semantics depending on the fact that path has been previously checked out or linked using dvs (see co and link) or it is checked in for the first time.
If path has been created by a check out operation, then a new version is created and checked in, provided that the current version is locked.
If path is new, 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.
If the -l option is specified, the new version is immediately 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.
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 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.
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.
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.
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.
% 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:
ssh -L 4321:serl.cs.colorado.edu:1234 hostcreates 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 pound 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_portHere 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.
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 "everything fine" 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.
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