DVS - Example

This document is intended to be a very short tutorial for the use of DVS. A reference guide is provided by the DVS man page. Even though it is not strictly necessary, it's good to know the basics of NUCM and its data model. To do so, refer to the NUCM documentation.

INDEX

0- Setting up the NUCM repository

The example here assumes that a NUCM database is correctly set up and that a NUCM server is running on serl.cs.colorado.edu using port 1969. Refer to the NUCM documentation for details. Here is a quick start-up procedure to create a NUCM repository and run the NUCM server: 
% cd /home/carzanig/test
% /tools/serl/nucm-2.0/bin/createrepository DVS
there should not be any file or directory named DVS in /home/carzanig/test. /tools/serl/nucm-2.0 is the directory in which NUCM-2.0 is installed. These commands create the repository that I will use in the following. Now I have to run the NUCM server: 
% /tools/serl/nucm-2.0/bin/nucmserver -port 1969 \
                                      -ndbhome
                                      /home/carzanig/test/DVS &
the nucmserver will use the tcp port 1969, so that port should not be used by any other application. The NUCM server (version < 2.1d) will occasionally print out some log messages, if you don't want those to be mixed with the other DVS messages, you can redirect stdout and stderr to /dev/null.

1- Example scenario

 In this example, I want to use DVS to maintain all the files related to a paper. My server is running on serl, so I can either run the client commands (dvs) from serl or run them from any other machine, provided that I set the NUCMHOST and NUCMPORT variables appropriately. 
% setenv NUCMHOST serl.cs.colorado.edu
% setenv NUCMPORT 1969

2- Setting up the initial workspace

 A NUCM database comes with a root collection named nucm_root. Thus, the first step is to add some files or some collections to the nucm_root. 
% cd ~
% dvs co nucm_root
% dvs lock nucm_root
this checks out and locks the last version of nucm_root (version 1 for an empty repository). Now a directory called nucm_root shows up in my home directory. Suppose I already have a directory that contains some files of my paper, e.g., ~/papers/icse98, then I just move (or copy) that directory into the workspace and check it in: 
% cd nucm_root
% mv ~/papers/icse99 .
% dvs ci -R -m "baseline" icse99
The -R option checks in recursively every file and directory in icse99. The -m "message" option sets the log message for all the check-in operations. If I don't specify -m "message", DVS asks for a log message for every file. I want to bind immediately icse99 to nucm_root, so I also check in nucm_root: 
% pwd
/home/serl/carzanig/nucm_root
% dvs ci .

3- Adding a file or a collection to an existing collection

 Obviously, I can also create and check in one single file, e.g., suppose I want to add the file abstract.tex to the icse99 directory: 
% dvs lock icse99
% cd icse99
% emacs abstract.tex 
% dvs ci abstract.tex
Similarly I can add a (sub)collection: 
% mkdir bib
% dvs ci bib

4- Modifying artifacts

 Once a base workspace is set-up I can go through the usual checkout+lock - edit - checkin cycle: 
% dvs co -l example.tex
% emacs example.tex
% dvs ci example.tex
Eventually, I have to check in the current working directory (icse99) to produce a new version of the main collection that includes the new files and the new versions: 
% dvs ci .

5- Closing artifacts

 I can remove the local workspace by issuing: 
% cd ..
% pwd
/home/serl/carzanig/nucm_root
% dvs close icse99
% cd ..
% dvs close nucm_root

6- Using artifacts from other servers (Distributed Cooperation)

 First I have to open my workspace again. Now I can open it directly in my paper directory : 
% cd ~/papers
% dvs co -R -l -last nucm_root:2/icse99
This contacts the default server (serl:1234) and checks out with lock the latest version of the icse99 collection. Now I have all the paper in ~/papers/icse99. Now I want to use a file that a friend of mine has stored in his nucm server on ipese0.elet.poimi.it:2345. I know that a NUCM server is running there and that there is a file called conclusion.tex in //ipese0.elet.poimi.it:2345/nucm_root:3/article:2/ 
% cd icse99
% dvs link //ipese0.elet.poimi.it:2345/nucm_root:3/article:2/conclusion.tex
By doing this I add to the icse99 collection a `pointer' to the conclusion.tex artifact. Now I can use check-in, check-out, lock, log, etc. on conclusion.tex as if it was a local artifact. Whenever necessary, DVS will access the remote server. 
% dvs co -l -last conclusion.tex
% emacs conclusion.tex
% dvs ci conclusion.tex
% dvs ci .
% dvs log conclusion.tex