Pragmatic Version Control Using CVS

jarich (Jared Richardson) writes "Many people will remember Andy Hunt and Dave Thomas's The Pragmatic Programmer (Slashdot review) as one of the better books on real-world best practices. It was a watershed book for many developers. However, The Pragmatic Programmer assumed a certain level of familiarity with some of the basic tools of the trade. For many readers, this simply wasn't a valid assumption, so Andy and Dave have started on a set of prequels to PragProg, called Starter Kits." Richardson reviews below that series' introduction to the Concurrent Versioning System, better known as CVS.

Pragmatic Version Control Using CVS
author	David Thomas and Andy Hunt
pages	159
publisher	Pragmatic Bookshelf
rating	10
reviewer	Jared Richardson
ISBN	0974514004
summary	A hands on CVS introduction and tutorial,

What's the approach?

The philosophy of this series is summed up on the Starter Kit website:

Software development is difficult enough; if you try to build on a shaky foundation it can make development almost impossible (which might account for the fact that about 50% of all software projects fail). You need a firm foundation: The Pragmatic Starter Kit is a set of basic, common-sense practices applicable in all software development environments. The techniques given in these three books are not expensive to implement and are not hard to learn, but can make the difference between being a success and being a statistic.

The first book in the series covers the what, why and how of software versioning, using CVS for the examples. It walks you through installing CVS clients, setting up your server, and using basic commands, then teaches advanced concepts. It is the new CVS handbook that can be used by both beginners and veterans.

Target Audience

This book, like The Pragmatic Programmer, should have very broad appeal. It should be required reading for any junior developers or CVS administrators, and it should be a bookshelf reference book for mid-level to senior developers. It is slanted heavily towards CVS, but given that CVS is free and widely used, that shouldn't prevent anyone from using the book to learn the concepts, even if their company uses another versioning system for production work.

What's to like?

As is usual for Thomas and Hunt's books, this one is a very easy read. The concepts are clearly laid out, with plenty of working examples throughout. There is a good coverage of the fundamentals as well as very advanced topics. Unlike most CVS books or tutorials, this text is clear and straightforward. It's easy to understand and follow. It's got the best coverage of CVS branching and merging that I've ever read!

What's to hate?

Honestly, there is not a lot here that I don't like. The introductory chapters are little too basic, but since the book is (partly) aimed at beginners, that's okay.

Why bother reading this book?

I've been using CVS for over six years now (including being the CVS admin at two companies) and this book covered a few very useful advanced topics that I had never even heard of. An example of this is the use of vendor tags (Chapter 10). Using this feature, you can have a local copy of your favorite open source project in your company's CVS server and make changes to it. You can then merge your local project with the new releases of the public project, and CVS will handle merging your changes with the public baseline. This feature is incredibly useful, but I didn't even know it existed until I read this book.

This book is a great introduction if you've never used a versioning system. By the time you've finished the book, you'll have installed CVS (client and server), created projects, created new files, merged changes, etc. If you already use versioning software, it can remind you about the features you've forgotten about (or never knew existed). This book is a great introduction and a great refresher too.

Where to buy?

Not so long ago in another Slashdot article, Andy and Dave suggested that in order to compete in the new global economy, we should all diversify our skill sets. To that end, this book is published under their new publishing company, The Pragmatic Bookshelf. You can buy copies from the Pragmatic Programmer's web site in both dead tree ($29.95) and PDF ($20.00) formats.

Summary

As we have come to expect from Andy and Dave, this is another great book. The technical content is rich and clear but it won't put you to sleep. It has appeal to both newbies and veteran developers. I give it '10 out of 10 slashes.'

---

Richardson met Hunt while he and Thomas were finishing up The Pragmatic Programmer and has reviewed each book that they have written since -- he makes no bones about liking their work.

more reviews

This site [verygeekybooks.com] has more reviews for this book.

Which book was a watershed event?

For me, I thought Code Complete [amazon.com] was the book for learning good coding.

On another note, does anyone else want to scream every time someone says 'best practice'?

GNU Arch is better than CVS

Time to bury CVS, not to praise it.

Check out Arch. [gnu.org]

Wait for IDE support, please...

I'm using Netbeans on Linux. The other developers are using JBuilder on Windows. I can set up a CVS server and everyone is happy. Arch won't do that yet (righ?).

I can't really dump CVS until there is support for the major IDEs (Including EMACS!).

Interestingly, Subversion support for Eclipse and Netbeans is available.

-- ac at work

Re:GNU Arch is better than CVS

I'll grant that Arch takes a while to grok -- I spent at least a few days wrapping my mind around it. Actually following along with the examples in the tutorial helps.

WRT your "unfinished" impression: The code itself is very clean, well-polished, readable, and robust. My only qualm is with the error-handling; there are lots and lots of sanity checks throughout, but the error messages aren't always as useful as they could be (asking for a revision that doesn't exist might give something like "File not found", or even more opaque, rather than "that revision does not exist"). Bugs that cause such things to happen without involvement of user error are extremely uncommon.

With regard to speed, I'm not sure if you'recomparing SVN to CVS or Arch; if the latter, be sure you're comparing against tla 1.1 or later with a revision library enabled. (Even more optimizations are on their way -- Chris Mason of SuSe has proposed a patch which brings the time to replay 100 changesets down to about 4 seconds in optimal conditions; some cleaned-up variant may well make it into tla 1.2 or 1.3).

what i hate about cvs

look at this:

cvs checkout -r mytag repository

cvs log -rmytag -d 'yyy-mm-dd'

two -r switches but... the first one has a space before the tag, the second one doesn't. when you look at the cederquist doco online the html really doesn't make this clear.

if this book addresses this one quirk it's worth a hundred bucks.

But does it have a GUI

Unless the source control software has a complicated GUI from which you can cut and paste stuff into powerpoint, and makes checking in a file, a longer process than software development, our bosses won't go for it

CVS good, ClearCase bad

CVS is great for version control. Don't get tempted by Rational's ClearCase product.

A full build of a sample project with CVS takes me 30 seconds. CC takes 7 min, 30 sec.

CVS doesn't need multi-site repositories, clearcase does if you have a lot of remote development.

CVS doesn't integrate with the kernel, so if CVS crashes it doesn't take your whole machine.

CVS has better add-on GUI tools for branching and comparison.

It is easy to create and apply patch files with CVS, something not easy to do with CC.

With CC, when you check out a file, you can't actually write to it. You have to loop and keep checking for the file to be 'writable' after check out. Even then, sometimes when CC marks the file as writable, it really isn't.

A batch update in CVS is easy, with CC you have to check out individual files. I have a script for this. A batch update takes about 20 minutes compaired to 45 seconds in CVS.

CVS is free.

CVS doesn't require as much training or support time as ClearCase.

ClearCase does have excellent command-line tools. It also has a lot more features. But you can probably live without them.

Re:CVS good, ClearCase bad

*sigh*.

Re versioning directory structures: If I rename the directory "a" to be called "b", and do a commit, I want people who do an update to suddenly have "a" renamed to "b" -- with all their local changes still intact. Subversion does it, Arch does it, CVS won't.

With atomic commits: I change 3 files. I want do a single commit that makes these 3 files part of one atomic change. If someone does an update and gets one of these, I want them to get all of them. (Say they're a change to a method description in a header, a change to the C file implementing that method, and a change to another file calling it -- if someone does an update and only gets one of the 3 they always have a broken tree; they should have all or none). CVS won't do that; Subversion will, Arch will.

See my other post [slashdot.org] for a bit more on why modern revision control systems are more useful.

Re:CVS good, ClearCase bad

My guess is that Arch is even less mature than Subversion though, since it appears to have not been around as long.

Actually, in practice, I've found Arch to be not only more featureful than Subversion, but much more robust as well.

Tom Lord (Arch's author) has written a few screeds with his interpretation of where the Subversion design and development process went wrong (to take so many man-hours to develop a product which, in his view, has severe design flaws); his arguments there are likely to be much better than any I could make here.

Re:CVS good, ClearCase bad

"Diagnosing SVN" [fifthvision.net] is one of the most widely linked. I think there've been a few others as well, but I couldn't locate them immediately.

Re:CVS good, ClearCase bad

Informative? Makea few bold assertions without proof or understanding and its informative?

I have supported development using CVS, SCCS, ClearCase, Kintana and BitKeeper. Each system has its advantages and disadvantages. For ClearCase, the biggest disadvantage is you have to read the manual.

"A full build of a sample project with CVS takes me 30 seconds. CC takes 7 min, 30 sec."

If I tune my mustand to run like crap, it will. Don't blame a tool if you haven't RTFM.

"CVS doesn't need multi-site repositories, clearcase does if you have a lot of remote development."

Bold assertion, care to provide even the slightest amount of example, or dare I say proof? How about a plan for using CVS across 500 developers in 8 sites, on 5 time zones. Ohh, and we are a worldwide company, so all developers need access to all code.

"CVS doesn't integrate with the kernel, so if CVS crashes it doesn't take your whole machine"

True. Thanks for providing context with a claim.

"CVS has better add-on GUI tools for branching and comparison."

Probably another RTFM. ClearCase has many powerful tools, but you have to learn how to use them. This in itself is a downfall as the quality of available software engineers continues to fall.

"It is easy to create and apply patch files with CVS, something not easy to do with CC."

Why? ....

"With CC, when you check out a file, you can't actually write to it. You have to loop and keep checking for the file to be 'writable' after check out. Even then, sometimes when CC marks the file as writable, it really isn't."

Your wrong, but I don't have time to cut an paste the manual over. You really should trying reading it sometime.

"A batch update in CVS is easy, with CC you have to check out individual files. I have a script for this. A batch update takes about 20 minutes compaired to 45 seconds in CVS."

I think your kinda sorta talking about a Snapshot view. Read the manual, pick up the nomenclature. It takes me 3 seconds to pick up all the changes in need in my dynamic....

"CVS is free."

True.

"CVS doesn't require as much training or support time as ClearCase."

I call bullshit. Its clear(har har) that you have never supported Software configuration management. CVS doesnt require training if all of you engineers already understand CVS. I expect the same to go for ClearCase...

"ClearCase does have excellent command-line tools. It also has a lot more features. But you can probably live without them. "

It has flexibility, which last time I looked increases strength. Learn what you need and ignore the rest.

Re:CVS good, ClearCase bad

No kidding.

I forgot to mention where ClearCase is much better than CVS though, and that is Sales People. No CVS people will take you golfing.

CVS cons?

I've always found CVS to be more trouble than it's worth. I do small-time development with Mac OS X (previously Project Builder, now Xcode) and like the *idea* behind CVS. But the articles/tutorials I've read are either how to install (which I have) and just go over the commands, or they're geared toward the expert. I haven't found much info on conceptual/fundmental questions, like on integrating with IDEs, for instance "do I check the entire development tree into CVS, or just the text files?" If it's just the text files, that seems like a lot of work. "How do I put my web site HTML files into a repository and still have the web server still be able to access it?" Overview stuff like that.

My current way of version control is the old way of just zipping up each release!

Pros for single user version control

I develop dozens of projects concurrently. Keeping all the development details straight can be difficult, particular when reapproaching a project that has been untouched for several months. The ability to back out non-obvious design mistakes, start speculative development branches, and distribute projects across multiple machines, depending on where I am at any point in time has made single version control a necessity for me.

Starting a project in CVS is simple.

Create a directory. Maybe add a descriptive text file or two. Run cvs import from within the directory. You'll then need to do a checkout, and you're ready to begin adding makefiles, source code, autoconf delights/madness. For what it's worth, I always rename the original directory before the checkout in case CVS has a glitch. Older CVS balked at overwriting the files; maybe that's still the case.

The last reason that I use source control even for projects that I am the sole developer is that I have on occassion, deleted critical files by mistake, and had to reimplement entire classes/modules under duress. It's a rare event, but with source control, I'm less stressed over the possibility of screwing up.

-Hope

Example CVS project starting point

There are two environment variables to be aware of, CVSROOT, and CVS_RSH. Setting CVSROOT isn't necessary, but it simplifies the cvs command line a little bit for first time users. I keep these variables in my .profile, but often as not, I use the cvs -d parameter to specify the exact repository. Once checked out, the project will remember where it came from. I use SSH for remote repositories, so the CVS_RSH environment variable is always set.

[~me]$ export CVSROOT=/path/to/local/cvs

or

[~me]$ export CVS_RSH=ssh
[~me]$ export CVSROOT=:ext:me@myserver:/path/to/remote/cvs

Generally, you may wish to start with a simple project and check it in before beginning your work in earnest. The fewer files the better, and if you've already run configure and have hundreds of non-source build files in the directory already, it can be time consuming to remove them, despite helpful make targets. I try to start with as few files as possible, and add all my source files explicitly.

[~me]$ mkdir foo; cd foo
[foo]$ touch ChangeLog
[foo]$ cvs import foo me initial
[foo]$ cd ..; rm foo

From here, one merely needs to checkout the project, add, and commit source files.

[~me]$ cvs checkout foo
[~me]$ cd foo
[foo]$ vi Makefile foo.c
[foo]$ cvs add Makefile foo.c
[foo]$ cvs commit

Obviously, a good bit of the first part could be scripted... I don't bother since I find project setup somewhat zen anyway. I enjoy the ceremony of it, and it's not a daily task anyway.

-Hope

Re:CVS cons?

No offense, but I hope I'm never in a project with you.
Programming (at any level, small OR large) without source control is like playing in the high trapeze without a net, yeah, you can do it, and if you're really good you'll get away with it for a while, but when you miss you'll be sorry.
Source control gives you a backup of your work, a storyline of what you've changed add to that the advantages of such a system when working with more people and I really can't imagine not having a source control system.
As a consultant, it is the first question I asked before taking on a project: what do you use for source control. I run away if they don't have one and are not willing to let me install one.

Slow Starter

I'm crazy about Andy and Dave's Pragmatic Programmer and Programming Ruby books, so naturally I had this book as well as Pragmatic Unit Testing on my Christmas list.

As someone whose been desparately trying to get a grasp on some advanced CVS concepts lately, especially vendor tags and tracking of third party sources, I'm a little disappointed at the slow start the book gets off to; it feels just a bit belabored reading another introdution to the basics, but I'm glad to hear there's good stuff further on. Guess I'll get back to it.

svn

who uses cvs anymore? [tigris.org] *giggle*

By the way, backports.org has a wonderful woody backport of subversion.

slashes

I give it '10 out of 10 slashes.'

Books are hard to read if you slash them to bits!

Shoehorning CVS to work with good dev practices...

is a heckuvalot of work, and not something I'm really sure is worthwhile -- particularly with the variety of alternatives available.

Aegis, GNU Arch (my personal favorite), Subversion, BitKeeper... all of these work around CVS's worst failings. What's unfortunate is how few people have had their expectations of what a revision control system should do set far too low by CVS.

A few examples of features one should expect of a modern revision control system:

• Easy branching - Branching and merging in CVS is a royal PITA, especially remerging branches which have had some changes mutually applied. CVS has a number of other design bugs related to branching -- for instance, files added on a branch suddenly show up on the HEAD when they shouldn't -- that need to be worked around, sometimes painfully.
• Corruption-resistant repository formats - Because CVS rewrites the ,v files every time a change is made, a CVS server that crashes in the middle of an operation can cause data loss. (Not all of the alternatives are better -- a few years back, for instance, the BitKeeper installation at my workplace had a tendency to corrupt its repositories at well. BitKeeper, however, can at least detect corruption -- in the case of CVS, it's often never picked up on 'till one tries to check out a particular old version. Arch avoids the whole issue by never rewriting or removing files which have been added to the repository, as well as supporting md5sums and cryptographic signatures in the 1.2 branch to detect either low-level corruption or malicious tampering).
• Changeset orientation - Actually checking in a set of related changes as one changeset, and attaching metadata (log entries and whatnot) to that complete set. This also makes CVS's "tagging" very cheap -- instead of needing to record the revision number of each file in the repository, only the changeset number of the repository need be tracked.
• Intuiting revision control history - A number of tools such as cvsps and cscvs (the latter which I help maintain) will analyze a CVS repository's history and break it down into changesets. This information can be used for a global "who-did-what" or the repository as a whole (whereas in CVS one can only view history for an individual file without extra tools), for importing a CVS repository's history into a changeset-oriented revision control system (most of cscvs's users use it strictly for CVS->Arch conversions), and the like. With CVS, this is a time-consuming and error-prone operation; much of the information just isn't stored on the server at all, so the tool being used needs to try to figure it out. Merges are even worse -- there's no metadata whatsoever available in CVS to distinguish a merge from any other commit, which makes a nmuber of advanced merging algorithms impossible. A modern revision control system, on the other hand, stores all this information up-front; there's no need for the error-prone and tedious process of having some 3rd-party tool intuit it by looking at the revision control history for each individual file.
• Automated testing - Having a test suite that automatically runs on every proposed commit is next to impossible to do accurately in CVS (as there's no good way to figure out which changes need to be grouped together into a test run), and CVS has no way to prevent a commit from happening until some external test has been run. Aegis, on the other hand, has this built in as core functionality, and Arch makes it trivial to script when using the available patch queue manager tool, tla-pqm.
• Distributed operation - This isn't often a dealbreaker in commercial environments, but it's exceedingly useful doing Free Software development; indeed, Linus has said that he'll under no circumstances consider switching to a revision control system without it. A system with distributed repository support (such as Arch, or BitKeeper -- Aegis has rudimentry support, but it's error-prone, while Subversion has none at all) can allow 3rd parties to crea

Re:Shoehorning CVS to work with good dev practices

Automated testing - Having a test suite that automatically runs on every proposed commit is next to impossible to do accurately in CVS (as there's no good way to figure out which changes need to be grouped together into a test run), and CVS has no way to prevent a commit from happening until some external test has been run.

Look up commitinfo in the CVS manual. It does both of these things.

How's about

Bitkeeper? I've seen a few good OSS projects use this and read some good things about it. Anyone, anyone? Bueller??

Online CVS reference

Open Source Development with CVS [red-bean.com] by Karl Fogel is a great online CVS manual and reference. I use it all the time.

JP

Silly CVS Uses

I've only met one person who used CVS and he used it to version control his mbox files! Obviously, CVS can be used on any text file but is it really useful for non-programmers?

vendor branches????

So.. does this book explain vendor branches *well*?

Does it explain why files stay on the vendor branch until you change them? (Which means if you change a couple files, they are on your main line, but the rest stay on the vendor branch).

That really bugs me (i.e., shouldn't the vendor branch be tagged with only vendor's version numbers, and your main line be only tagged with YOUR tags, instead of mixed on both branches?)

I found out that "cvs admin -b" will move the vendor code to the main line, so I always run that command after importing vendor branches. But it really doesn't make sense.

It's much more logical to do vendor branching in Subversion (even though you are technically doing them "by hand", like all tagging and branching in svn).

Anybody know what I'm talking about, or is this like "super-advanced CVS for anal pricks"? Maybe. :-)

Anyway I hope this book is good. I found the O'Reilly book to be awful. I love their Ruby book.

no one has mentioned TortoiseCVS

Its pretty amazing that no one has mentioned TortoiseCVS [tortoisecvs.org] yet. If you are using CVS and are stuck on the windows platform, then Tortoise CVS is a god send.

No Amazon?

Not very pragmatic if I can't buy it at Amazon. I don't live in the US and I don't have a credit card.

Some facts about Subversion (and CVS).

A number of posters ask why would one even want to use CVS considering its known faults? Although I'm personally partial to Subversion [tigris.org], choosing CVS doesn't seem unreasonable. CVS is no less useful today than it was (say) two years ago, before Arch or Subversion or any of the other new kids on the block were ready. If you want something that does the job and whose problems are known, CVS is not a bad choice.

But on to the real reason for my post:

Some of the posts here make simply wrong statements about Subversion. Below are corrections.

1. Subversion does not require a Unix user account per vc user. Furthermore, this is true not just with the WebDAV (http://) access method, but also with the svnserve (svn://) method. Some posts said otherwise; not sure why.

2. Subversion does *not* require Apache, nor does it require you to use the WebDAV protocol for repository access. Apache/WebDAV is one of two entirely independent network access methods. The other is a custom protocol (think of it like CVS pserver) using a custom server (svnserve) and its own URL space, "svn://".

3. Subversion is not in Alpha anymore, it is in Beta. This was a recent transition, so it's understandable that people wouldn't have known about it.

4. Someone said you can't make client-side graphical reports about revisions and differences, because the client doesn't have access to the right information. I think this person must have read and misunderstood a highly technical mailing list thread. The client does have access to the necessary information already (see 'svn log -v' for starters).

People with further questions about Subversion should please come to [e-mail], or irc.freenode.net, channel #svn. Hope to see you there!

By the way, I have not used Arch in a long time, so can't comment on the differences between it and Subversion.

Re:Perforce

What's happening with subversion? Is it useable yet?

Yep. I started using it about a month ago. Within three days I was so enamoured of it that I switched all my projects to it. Anyone who has used CVS should be able to switch almost without retraining. And the best thing of all is that the documentation (a downloadable book) is thorough, well-written, up-to-date, and full of useful examples. This project should win some sort of prize; it deserves it.

Re:Perforce

Second that...Perforce is great. Used Visual Source Safe (now with more repository corruption!), MKS (sweet jebus), StarTeam, CVS and Perforce...Perforce is the best out of those. Very simple but powerful command-line syntax. Good Windows client and VC++ integration. Works the way you would expect it to.

Re:Perforce

I love the functionality of Perforce. I've used it at several jobs.

I hate the price, and their weird-ass pricing scheme. For a quick case of sticker-shock, just go to http://www.perforce.com/perforce/price.html

-Chris

Re:Perforce

When our dev team outgrew CVS, we evaluated about 20 CSM products, including Perforce, Telelogic/Continuus CM, CCC Harvest, StarTeam, BitKeeper, All Change, and ClearCase (we actually managed to get Telelogic & the Rational guys to come down for a *free* live demos). We found that they all fall into one of three pricing tiers:

I. Free or nearly free--includes: CVS & SubVersion.

II. Under $1000 per seat--includes: AccuRev & Continuus CM.

III. More $$$ than you can possibly imagine--includes: ClearCase & StarTeam.

To cut it short, we eventually went with AccuRev [accurev.com], due mostly to environmental and budgeting restrictions. It's an unobtrusive, often maddingly slow, Java-based product, which happily fits most of our needs.

There's a huge field of versioning products out there, most of which can only be found on poorly documented company websites, many without demo's. And each of them promises to be the last word in SCM, but with little to no comparison between vendors. (Oh sure, product FooSCM includes LifeCycle Management, but the definition & amount of "Lifecycle" varies greatly from one product to the next!)

Caveat emptor!

Re:Subversion - CVS is dead and burried within 200

I hope you don't mind, I've saved your quote about trees. It cracks me up, along with other Subversion developers.

If you want a serious answer: we have several db tables. The values in the tables are lisp-like "s-expressions" that hold real data and keys to other tables. It's a way of getting "columns" when you don't have a real SQL backend. And by the way, it works extremely well.

(We do have future plans, however, to give the repository a real SQL backend someday.)