I use CVS for just about any text files -- C-code, Matlab, HTML, LaTeX. Although I'm not a big expert in this, these steps will get you started. This tutorial is designed to be run on any UNIX/LINUX systems.
If you want the even quicker and dirtier start to CVS, click here.
cvs -d ~/cvsroot init
Now you may want to add the following lines to your
.cshrc, .bash_profile, etc file: (to find out what shell you
are running, type
|#CVS Environment variables
setenv CVSROOT $HOME/cvsroot
setenv CVSEDITOR emacs
|   ||#CVS Environment variables
That just tells the system where your default repository is, and for now you only need one repository. Now make sure that environment variable is set, by executing the line that you added, or equivalently:
(or .cshrc if applicable).
cp -r ~brian/cvsexample .
Otherwise, if you are running on another linux/unix system, download the cvsexample.tar file. Move it to your home directory (~) and uncompress it using the following command:
tar -xvf cvsexample.tar
From here on, assume that this is important data that you don't want to lose -- next time you do this that will be the case!
Next, back up the whole project directory!
cp -r cvsexample/* cvsexample2/
(of course there are other ways to do this!)
Back it up again if you really care, because now you are going to erase your whole original cvsexample directory...
rm -r cvsexample/*
Now we will add the (empty) cvsexample directory to CVS:
cvs import -m "dir structure" cvsexample yourname start
"yourname" and "start" are really unimportant - they are just version and "vendor" labels. "cvsexample" tells CVS to store the archive in a directory cvsexample. Also, when you checkout cvsexample later, it will create a directory called cvsexample.
Note that any files/directories that are in cvsexample/ when you do the import command will be under CVS control. Sometimes that's desireable -- ie if you have three subdirectories of cvsexample that you want in CVS, just leave the empty directories. However, sometimes you don't want files under CVS, or you want to put them in as binary files. Thus I recommend adding them later.
Now you completely erase ~/cvsexample, because you're going to check it out as a CVS working directory:
rm -r cvsexample
cvs checkout cvsexample
Now you have a directory called cvsexample, which should have a subdirectory called CVS. (all directories under CVS control will have this subdirectory).
cvs add cartilage
cp ~/cvsexample2/*.tex .
Now, for any files that you want CVS to control, register them in the repository:
cvs add sample.tex
or something like
cvs add *.tex
You should get a message saying that CVS has added the files,
but you should use CVS commit to permanently add them. Go ahead
and commit them:
cvs commit -m "original file" sample.tex
cvs commit -m "original files" *.tex
If you omit the -m "original file" then cvs will start up your default editor for you to type a log message. This latter form is usually more useful. Write good log messages!
Probably all you got was a message like "cvs update: Updating ." Now "edit" ~/cvsexample.sample.tex by entering:
cp ~/cvsexample2/sample.1 ./sample.tex
Run cvs update again. The result of update will have the letter M next to the sample.tex, which you changed. This indicates that you have modified the file. Other letters you sometimes get are P, which means CVS has patched the file from other updates in the repository, or U, which means CVS has copied a new file that wasn't yet in the working directory.
Let's look at what we've changed with cvs diff:
cvs diff sample.tex
CVS prints a nice summary of what you've changed compared with the repository version. Now check in the change to the repository:
cvs commit sample.tex
When you do this, CVS pops up an editor. Just type a line like "first changes to file" on the first line and save/exit the editor.
Notice that the revision number is now 1.2.
cvs checkout cvsexample
This should create the cvsexample working directory within the directory dummyuser. Have a look at sample.tex, and note that the "edit" you made by replacing it with sample.1 is there. Now we'll assume that you and the dummy user both simultaneously make changes to sample.tex. First the dummy user:
cp ~/cvsexample2/sample.2 ./sample.tex
cvs commit -m "change by dummy user" sample.tex
cp ~/cvsexample2/sample.3 ./sample.tex
cvs commit sample.tex
Edit sample.tex and you see that it shows you the lines that you need to resolve. Choose some balance between what you "wrote" and what the dummy user wrote, and just leave the file the way you want it to be. Then run cvs commit again.
Conflicts are a pain, but much less of a pain with CVS. You can avoid conflicts by using CVS update frequently. In that case, you might see the change that someone else has already made before you make a conflicting change. Of course sometimes conflicts will be unavoidable.
Next, you decide to add some files to the cartilage subdirectory:
cp ~/cvsexample2/cartilage/*.tex .
cp ~/cvsexample2/secondsample.c .
Just type sensible comments when you do the commit.
Now become the dummy user again, and update the cartilage subdirectory:
Notice that the .tex files are in the cartilage subdirectory. Change back one directory to cvs example and you see that secondsample.c is not there. That's because you ran the update from the subdirectory. To verify this, run cvs update from ~/dummyuser/cvsexample and you should see secondsample.c there now. The reverse if this is different though -- if you update the root, the subdirectories will all be updated. This is both useful and important to understand!
cvs log sample.tex
CVS prints a list of the log messages that you have added. A really nice feature is to have CVS just put the log messages in a comment block in the file each time changes are committed. Nicer yet is the fact the CVS does this intelligently enough that that comment blocks for latex, Matlab, html or C all work. Try it - put as the first line of sample.tex % XLogX, but replace the X with $. (Since this html file is controlled in my own CVS repository, I had to skew this a bit!
Now commit the changes and look at sample.tex. You should get your most recent comment (previous comments are not added). For fun, edit the new file, and remove the comment block and replace it with /* XLogX */ (again replace X with $) and commit the change again.
For another example, just look at the source of this web page with "view source" on your browser. Note that there are CVS log comments in this file!
cvs tag Clinical-Release-1.0
The tag text can be anything that you like, so you can
make good use of it. You could later checkout the tagged
version of the project with
cvs checkout -r Clinical-Release-1.0 cvsexample
Now you can check out a project from the different filesystem with the -d option, which tells CVS to use a different repository, and the :ext to tell it to use an external location. For example:
cvs -d :ext:bah@lelandmachine:/afs/ir.stanford.edu/users/b/a/bah/cvsroot checkout cvsexample
Now all your cvs commands will run through ssh to the remote system. You can avoid typing your password every time by putting the appropriate public key in your .ssh/known_hosts file. Since the remote repository location is stored in CVS/Root, you only have to type the :ext part once.
CVS has fully compatible versions on Unix/Linux, Windows and MacOS. There are also simpler interfaces, web-based, or in Windows and Mac. When you're ready, here are some other links: