CVS does not store permissions and ownerships on files. You cannot flag a file under CVS control as world readable, for instance. When you check something out from CVS, the files come to your workstation and CVS chowns and chmods them according to your umask. When you commit changes, CVS pulls in your changes, but doesn't modify the permissions in the repository. Most projects use different group permissions on the repository so they can restrict access to project developers.

People using CVS for more than software development make use of the post operation scripts to overcome this limitation. You can tell CVS to run a script or program after a CVS update or commit. In this script you can set permissions and other such things that CVS doesn't handle.

You cannot store symbolic links in CVS. Forget about it, ain't gonna happen. Use the script hack above or just say good bye to symbolic links forever.

CVS provides source code control. You can check out old versions, generate patches between releases, and many other tasks specific to software development. To perform these tasks, CVS must deal with plain text files. This is how it can track changes between the files. This presents a major issue for binary files. So much of an issue that CVS just doesn't handle binary files. Now we're starting to have some problems. To get around this problem, we can flag a file as 'binary' and CVS won't track changes to it. It will just make sure one copy is in the repository. Generally speaking, this works fine, but it means you can't use CVS to track changes between, say, JPEG image files.

Once a directory is added in a CVS project, you can't delete it. Remember I said that CVS never deletes a file, it just moves them in to the attic? Well, if you checkout an old release that had a now deleted file in a now deleted directory, CVS needs to know where to put it. The empty directory is where it will put that. Because of this, CVS can think of empty directories as deleted, which is what you want to do.

Generally speaking, CVS does not like to deal with spaces in filenames. I have seen tricks to make CVS deal with this, but I prefer to not have spaces in filenames anyway. For some people, this may present an issue.

The import command is for creating new CVS-controlled projects. You run this command from the directory you want in CVS. For software development projects, this is usually your source directory. To import the current directory, use this command:

cvs import -d project-namevendor-tagrelease-tag

The -d flag tells CVS to use the file's mtime as the import time. This way you can import projects that haven't been under CVS control for years, the timestamps are preserved this way. The project name is what you want to call the CVS module, the vendor-tag is mostly usually, and the release-tag is just a symbolic name to represent the import. For vendor tag I use BURDELL. For the release tag on import operations, I use 'start'.

The checkout command is what most people are probably familiar with. The simplest syntax is:

cvs checkout project module

Which checks out the latest revision of the specified module. Adding the -r [rev] switch will check out a specific revision.

This commands works like the checkout command, but it does not "check out" a copy to work on. That is, the CVS server does not know you are working on that copy. This command mainly exists for creating source archives for distributions. Once you tag the release, you export it to another directory and it's free of the CVS repository and does not have those 'CVS' subdirectories all throughout the tree.

The add command is used to add files to a module you have checked out. You must specify each file to add:

cvs add files...

If you want to add a directory, use the add command on the directory, but then change in to the directory and add each file. The add command has a special flag for adding binary files, the -kb switch. Use this switch when you are adding any file that is not plain text.

To remove a file from a module (or project), you must use the cvs remove command. The biggest problem people have with this is that you must specify each file separately. It's really not that big of an issue once an entire project is under CVS control, you'll find that you rarely remove large sets of files. If you need to remove an entire directory tree that's under CVS control, use the -R switch to recursively remove the directory. The syntax:

cvs remove [-R] [-f] files...

This CVS command has one major annoyance, you cannot run 'cvs remove' on a file until you actually rm it from the filesystem. To get around this default behavior, use the -f switch on this command to tell CVS to rm the file before removing it from the project. Very useful.

You will use this command as much as the commit command. The CVS update command brings your local copy of the project up to date with all the changes available in the repository since you last updated. This command merges differences and also lets you know of merge conflicts. The syntax:

cvs update

Run this command from the main project directory and CVS will check the repository and pull down and merge all the changes. The output from this command can be a bit cryptic. The program displays a letter indicating the operation, followed by the file involved with that operation. Here are the letter codes you will most likely see:

The two options I use with cvs update are -d and -P. These two options bring down all directories in the module and then "prune" empty ones, which we assume are deleted directories.

If you get merge conflicts (you will), cvs does this really nice thing by default where it stomps all over your copy of the file in conflict. It is up to you to then move the file out of the way, get the copy from the repository, diff the files, and merge the changes by hand. If you are predicting merge conflicts, it's a good idea to use the common CVS option -n, which reports what would be done to your copy without actually doing it. So running this command:

cvs -n update 2 <&1 | grep "^C "

Will report what files have merge conflicts without stomping all over them.

This command is used for software development projects under CVS control. If you're tracking your home directory with CVS, you probably won't make releases of it at various points.

The tag commands marks the state of the repository with a symbolic name. Once you tag the module, you can later checkout a specific tag by name.

The tag command places the symbolic tag on your checked out copy of the project, the rtag command puts the tag in the repository and does not affect your copy.

When working with branches, you make use of the tag command. You can create and merge branches with the tag command.

When you make commits, CVS will prompt you for a log entry. Using this wisely will produce a log for the project that can be referred to later. Many people skip this step. It really doesn't matter, but I like logs, it makes tracking down changes easy. With a CVS log, you get the file listing, the revision numbers, and the annotation so you can quickly get back to working copies of files.

The diff and rdiff commands can display the changes between revisions of files in either unified or context format. If you need to manually resolve a merge conflict, generate a patch to a tagged release based on the current developmental copy, or to see what you changed when you broke something, the diff command is what you want to use. The syntax:

cvs diff -r rev -r revfiles...

The diff command has a lot of options, most of which fall through to the diff command. You can diff specific revisions, files from specific dates, and you can process directories recursively to generate large patches.

The CVS commands that begin with an 'r' are like the similar command above, but they operate on the repository instead of the checked out copy.

You may also be familiar with the 'login' and 'logout' commands. These are generally used with the CVS pserver mechanism and not when a repository serves via ssh.

There are some common CVS options, such as -z (for compression) that apply to all CVS commands. You can use the --help-options switch to see a list of those.

On the subject of command options, the location on the command line where you put options does matter. There are generic CVS options and command specific options. You need to follow this order when using options:

cvs [common opts] [cvs command] [command opts] files or something

You can alias the CVS commands to the command plus the common options you prefer. This is done in the ~/.cvsrc file.

CVS uses the RCS file format to track changes. Because of this, you can make use of special RCS variables within your plain text files. A common one is $Id$, which expands to a description containing the RCS file name, a timestamp, and the revision number. Another RCS variable is $Log$ which expands to the commit log for the file. This can get really long for files that change often (.c files for development projects), but for files that rarely change, it can provide a quick way to look at the log. A list of the common RCS variables:

This also brings up a good point about CVS. The RCS man pages apply to CVS, mostly. Specifically the co(1), ci(1), rcsintro(1), and rcs(1) man pages.

When you get a new user account on a system, you are given a place for your files, your home directory. Over time you get more and more shell accounts, sometimes even on your own machines and you begin to lose track of where files are and you begin to have trouble maintaining the environment profiles between them all. This is a problem I've fought with for a long time, until I read the article by Joey Hess in the September 2002 Linux Journal. Joey explained how you can put CVS to work synchronizing your home directory. It never occurred to me to try this, but I decided to give it a shot. It's been working great between my machines. Below is a short description of what I did to move my life in to CVS.

Projects under CVS require some thought. Not being able to freely remove directories and having files always exist means you can't just throw things anywhere. Well, I guess you could do that, but it would make for a CVS managed mess. So, I created a new directory as the working tree for what would become my new home directory. Inside this directory I have these subdirectories:

That's it. I keep classwork under the gt subdirectory, general 'work' goes under doc in an appropriate subdirectory, and so forth. Keeping to this structure will ensure your cvs attic doesn't grow enormous.

I start by importing an empty directory structure. I will be holding plain text as well as binary files in my home directory, so I need to specify the -kb switch on some of them.

cvs import -d david-homedir BURDELL start

Once the import is complete, I remove the directory I just imported and check it out from CVS.

With my empty directory, I start adding in files one at a time. I did several subdirectories at once and then I'd commit the changes. This process took a while, but I only have to do it once.

Remember to use the -kb flag for binary files. Use cvs commit to place the new files in the repository.

Since my home directory is huge, I can quickly lose track of what I've added to CVS and what I haven't. I use the cvs update command and look at the lines beginning with "?" and then go and handle those files. I pretty much used the update command as my checklist for what I still needed to merge in.

With everything in CVS, you can now take your home directory to CVS. It's somewhat tricky, but here's what I did.

$ cvs commit                    # final commit
$ cd                            # change to my home directory
$ cd ..                         # go up one level (/usr/home on my system)
$ rm -rf ~/*                    # remove everything in my home directory
$ cvs co -d david david-homedir # check out my home directory

Now, I went to another terminal and tried logging in. Once I verified everything was working, I logged out of the shell I did the checkout from and started using normal shells.

Living in CVS isn't hard, it just requires a few extra commands on top of the normal commands you type.

At the end of each day, you should do a cvs commit to commit your work for the day to CVS. Each time you start working on something new, start in a logical place and do cvs add on those files and directories. After about a week, the CVS commands become second nature.