How to Collaborate Via CVS Repository

A. Overview
B. How to join the system
C. Setting up environmental variables
D. How to checkout and update modules
E. How to create new modules
F. How to use tags

A. OVERVIEW

The following notes shows how to collaborate (say, in writing a paper) via a remote CVS repository.

For security reasons, we need to use SSH to access the CVS directory. Each collaborator (henceforth called "user") must use public-key encryption. Henceforth, the administrator at NYU is called "we".

For our example below, the remote CVS repository is at "access.cims.nyu.edu". You, the user, will have the user name of "e-friend" or "exact".

What is the difference between "exact" and "e-friend"? The e-friend account only has permission to access our CVS files. The exact account is meant for internal use, and has more permissions, to do things like ssh or sftp.

B. HOW TO JOIN THE SYSTEM

Before a user can get access to our CVS repository, he/she must take the following steps to create a private-public key pair in the OpenSSH format, and send us the public part.

STEP 1:

The user must first create a private-public key pair:

	> ssh-keygen -t dsa -b 1024

NOTE: ">" indicates a unix prompt. This system works just as well on a cygwin environment (in Windows) and on Linux as well. Cygwin is my preferred way of working remotely, if one has to use Windows.

This causes ssh-keygen to create 2 files, named id_dsa and id_dsa.pub. The first file contains the private-public key pair, the second contains just the public key.

Note that this command is interactive: it will prompt the user for (1) a full-path file name for storing the private-public key pair (default is ~/.ssh/id_dsa). and (2) a "passphrase", which is a password to protect your private key.

For (1), you can accept the default, unless this will clobber a previous file by that name. For (2), you can just hit a return (no passphrase).

STEP 2:

The user send us the public key file (i.e., id_dsa.pub in above example).

FOR SOME USERS, you may need to send us a DIFFERENT file. That is because we expect id_dsa.pub to be in "OpenSSH" format. For instance, on cygwin platform, the file id_dsa.pub is in "SSH2" format, which is not compatible with our system. In this case, you need to manually produce the required public key file, as follows:

	> ssh-keygen -x > Yap_dsa.pub

This will prompt you for the input file containing the private-public key. The default file will be indicated on your screen. (This file might be /home/yap/.ssh/id_rsa.) You should just enter the full-path name for id_dsa.pub. This creates the file Yap_dsa.pub. You then send this file to us (instead of id_dsa.pub).

Here is an example of a public key in OpenSSH format:

ssh-dss AAAAB3NzaC1kc3MAAACBAOKbzNQDYCcgvA+h5x+sHwVqNU3tMrVuYKh+A+CT5fT0gibFMxt9 Stq3n7lZYrNdve2xt51xqNNhHaI8mXj6RVI+6j4oafoB519jZp6sskf3aVAvDK1R5e3xAgBL9ta3acLS 0Yv6OMfTbzpe0Q8Qed5Q1AKgc9cGpKDndRMBZnr/AAAAFQCVwAax/pEYTUjp4kPQz53gvHn3BwAAAIBw 2IA05oq4Qgx8J1ZbMr0/Hb3Neb0C1+xSqetNa/BFhtrMRGJfV+LICeqBWgpT6KJnxsvFgP0/EqMzQOLP 9g5rq6lbDyzhsvr0UP6JVuhNYSa5j73hYO5yjk45wNmr1J/hJG3gANXKib+tbTcYJbu4hfWOC74FTYE9 poXjds1hIwAAAIEAlw/6fnH+WNP/yPgy4ArZPtiCu+H8j24F59sJ/xDyQ4xdwxXTtOiZVm27sdHie9v9 UXPzD8aAM+ikMWWYJ0trnYkUBs4rKhhuqxo9SaLHLZsMQBawMtOuEbjWzMJMuTfRDgJYe4k+zcT/R2bD GZsWojWUUtpYh3z59hTw6uq6tE0= Administrator@YAPGEOMETRY

Arno Eigenwillig points out that the public key in OpenSSH format is one long line in (ASCII) text (but in the above example, we artificially break it up after each 80 characters, for readability). In constrast, the public key in the SSH2 format spans several lines, the first of which reads
---- BEGIN SSH2 PUBLIC KEY ----
Using the ssh-agent and ssh-add (see man pages), one can secure one's key with a passphrase but avoid the hassle of being asked about it repeatedly.

STEP 3:

You next send us an email to inform us of the arrival of the public key file. We will enter this information into an "authorization file". Then we send you an email to (1) inform you that you now have permission use CVS on our system, (2) what the name of the module is, and (3) whether to use exact or e-friend account.
You may now proceed to Parts C and D.

C. SETTING UP ENVIRONMENTAL VARIABLES

The behaviour of CVS is dependent on values of certain environmental variables.

In these examples, we assume that your account is "e-friend". So if your account is "exact", you must replace all occurences of "e-friend" by "exact".

Two environmental variables CVS_RSH and CVSROOT must be set up first. For example, in bash shell:

        > export CVS_RSH=ssh
        > export CVSROOT=:ext:e-friend@access.cims.nyu.edu:/home/exact/cvsroot

For csh or tcsh shells, the corresponding commands are:

	> setenv CVS_RSH "ssh"
	> setenv CVSROOT ":ext:e-friend@access.cims.nyu.edu:/home/exact/cvsroot"

We suggest putting these into your startup shell script (e.g., .bashrc for bash).

D. HOW TO USE CVS: CHECKOUT AND UPDATE MODULES

After the above steps, you are ready to use our cvs. Suppose someone has already set up a "module" in cvs. Each module has a name (which is just a directory path).

E.g., 2004/FirstPaper, 2004/SecondPaper, 2004/FirstPaper/Abstract, 2004/FirstPaper/Conference, 2004/FirstPaper/Journal, etc.

Let us say that the module name is "ourPaper". Typically, you do these steps:

You first go to your local directory where you like to store the directory "ourPaper". E.g., if the directory is "allPapers", then
```
	> cd ~/allPapers
```
Then you checkout "ourPaper":
```
	> cvs co allPapers  
```
This creates the directory "allPapers" together with any subdirectory and files.

Now you can edit any file or add files to ourPaper. Skip this if you are familiar with using cvs. Say the file you modified is called "p.tex". To put your changes back into CVS, you typically take 3 actions:

	> cvs diff p.tex	-- this shows any differences between
				your version and the corresponding
				version in cvs (there may be more recent
				versions, but diff will not show them).  
				You can edit your version of p.tex based
				on this information.

	> cvs update p.tex	-- to merge what is in the directory with
				what is in your local version.
				If there are any conflicts, these will
				be marked between the lines marked by
				<<<<<< and >>>>>>.  E.g.,

				<<<<<<< fileName.tex =======
				...cvs version
				======
				...your local version
				>>>>>>> version number

				You should resolve the conflict (typically,
				by deleting your version or the cvs version).
				Remove the marker lines with <<<< or >>>> too.
				
	> cvs commit p.tex	-- this updates CVS so that your local p.tex
				is also the latest version of p.tex.

To summarize: to work on any file, you need to

(1) get a local copy of the file
(2) modify the local copy
(3) do a "diff" with what is in cvs (someone may have modified it since the last checkout)
(4) update from cvs (this will merge your changes with what is in cvs)
(5) resolve any conflict (if there are any)
(6) commit your changes

Hope this will get you started.

E. HOW TO CREATE NEW MODULES IN CVS

Suppose you want to create a new module named "2004/thirdPaper".

First create your files in some temporary directory, say in "tmp".
Go to "tmp" and type:
```
	> cvs import 2004/thirdPaper vendor release
	
```
where "vendor" and "release" is not really used by us, but are mandatory arguments. You can type anything for these arguments if you like.
The system should say something like "no conflicts", in which case you have successfully created the module.
Now check out a copy of the module that you have just created. Suppose you want to place this module under the directory "~/allPapers/". Then do:
```
	> cd ~/allPapers
	> cvs co -d 2004/thirdPaper 2004/thirdPaper
	
```
You now have a local copy of the module. Do all your work here.
You may discard the original files in "tmp".

F. HOW TO USE TAGS and VERSIONS

Often you want to create a snapshot of your module at a given moment in time. E.g., after you submitted a paper to the journal, you want to tag the current version as "SUBMITTED". Subsequently, you can checkout this particular version under the tag "SUBMITTED".

The issues of tagging is complicated by the existence of tags for branches. But here, we give instructions for the simplest use of tags, where you just want a copy frozen in time. So you are not allowed to check in any changes to the "SUBMITTED" version. CVS calls such "SUBMITTED" a sticky tag (also known as a pure tag).

There are three basic commands to learn: how to create a tag, how to checkout a tagged version, and how to find the available tags.

TO TAG THE CURRENT VERSION:
```
	cvs tag [tagname]
	
```

TO CHECKOUT A TAGGED VERSION:

	cvs checkout -r [tag name] [module name]

TO FIND OUT ALL THE TAGS AVAILABLE WITH A GIVEN MODULE:
```
	cvs status -v [file name]
	
```
where [file name] is any file in the module.

Tagging is meant for all the files in a module. But each individual file has its own automatic tag, called version number. Here are some ways to use version numbers:

HOW TO MERGE AN OLDER VERSION INTO THE CURRENT ONE
Perhaps you want to do this to retrieve some deleted text found in the older version.
Suppose the current version of a file "foo" is 1.30, but you want to MERGE it with version 1.26. Use the "update" command:
```
	% cvs update -r 1.26 foo
	
```
The merged file will indicate any conflicts in the usual way. You should edit to remove the conflicts and do any other changes you want.
There is a slight problem when you try to commit it: you will be prevented because this version of "foo" has been marked with a "version 1.26 sticky tag". You can see this sticky information using
```
	% cvs status foo
	
```
So you must first remove the sticky tag information as follows:
```
	% cvs update -A
	or
	% cvs update -A foo 
	
```
Now you commit this merged file; it will become version 1.31.

Let send us your feedback to improve these instructions! --Chee