CVS: Getting into the mind of CVS and how it works

Since some of my posts are discussing manipulating CVS backend files, it is important to now explain a little bit about the way CVS works.

CVS only cares about its own copy of the code in $CVSROOT. Each folder under $CVSROOT is called a module. The files in here are kept in the same structure with the same filenames, EXCEPT every file has a ",v" at the end of it. No need to go into why, just understand that these are the backend files of files under CVS control and that each ",v" file contains all the version history of the file in it. Developers should NEVER be here, never look here, and I have probably done wrong just telling you about it because your curiosity may cause you to go look in this folder. Screwing up something here can be disastrous.

So why doesn't CVS care about your files? It doesn't need to until you try to do something using the "cvs" command. First you do a checkout to get code to your local area to work on.

$ cvs co <module>

The "co" is a shortcut for "checkout" but either can be used. This will get the latest copy of the code out of CVS, called the HEAD...or the HEAD of the TRUNK. We can talk more about HEAD, TRUNK, BRANCH later when we talk about proper revision control

Once the code is checked out, you will notice a CVS sub-folder in every directory. This CVS folder contains the information about
1. Where the CVS repository is (can even be on a remote machine -- this may hardcode usernames)
2. What module you have checked out from the repository
3. What tag/branch if any
4. What versions of every file is checked out

If this CVS folder gets deleted, there is no link back to CVS. When you do a commit to CVS, it goes into this folder and looks up the data on where to put the files. It will also do checks to make sure you have the latest code prior to allowing you to commit. There is a nuance to be aware of when using code on remote servers: If $CVSROOT is on a remote machine, then your Root file in CVS folder probably contains a :pserver: line with your username hardcoded. This means that, if you are sharing code with another developer (copy and paste whole directories), they will get your username all over the place. I wrote another blog post on how to quickly correct this problem. If the CVS repository is on the same server as you are checking out code to, this problem isn't manifest.

We'll talk more in later posts about how to manipulate CVS in the backend for restructuring code. This a dangerous, but occasionally necessary task.

CodeProject

CVS: Update a Tagged set of files to Head

If you create a minimal set and tag it from a larger set of code in a module, you may want to preserve this set of code, but get later versions. This is useful for delivery when we create a minimal set to determine ONLY the files appropriate for sending to the customer, then using that same list for each subsequent delivery rather than going through the effort again.

First check out the old tag:

cvs co -r <tag_name> <module_name>

Then tell CVS to go inside that folder/module that you checked out and update files to HEAD...but ONLY those files, not the entire repository.

find -type f ! -path '*CVS*' | sort | xargs -n1 cvs update -A

Now if you want to retag just these files, use the instructions for "Tagging Individual Files" in an earlier post.

CodeProject

CVS: Tagging Individual Files

In order to tag individual files for creating a minimal set for instance, delete all the extra files from the directory, but leave in the CVS directories. Then run the following command replacing GENERIC_TAG_NAME with the tag for CVS.

$ find -type f ! -path '*CVS*' | xargs -n1 cvs tag GENERIC_TAG_NAME

This will find all files, ignoring everything in the CVS folders, and then run the cvs tag command on them. If it fails to tag one file, it will continue on to the next.

CVS: Fixing a misnamed tag

If importing code and the wrong tag was used, before anyone gets messed up, do the following:

Create a new tag pointing to the old tag:

$ cvs rtag -r <Existing_WRONG_Tag> <New_Tag> <module>

Delete the old tag:

$ cvs rtag -d <Existing_WRONG_Tag> <module>

This is how you would rename any tag, not just one made on import of new code, but the cautionary note is that messing around with existing tags can be very dangerous. If the tag is already used in a release, then you have broken your traceability. If the tag is something developers have checked out already, there is now a breakdown in consistency of everyone's configuration. Use this with caution. Luckily, tags do not do any permanent damage to the code repository, but for traceability, try not to change them at will.