Introduction to Version Control

a part of MarkD's Guide to CVS
When I was first introduced to version control, my first reaction was "wow, what a waste of time. Just let me work on my code." As I started using it for day to day professional work, I warmed up to the concept. Now, ten years later, I'm very uncomfortable if I'm not working with version control.

Version Control, a.k.a. Source Code Control, is where you let the computer keep track of the changes you make to a file, whether it be source code, documentation, or graphics files. You tell the version control (VC) system "remember this file". You make changes to the file, then tell the VC system to "commit", or remember these changes. Keep this up, and soon you'll have a complete history of all of the changes to the file. Since the computer now has this complete history, it can regenerate the file as it was at any point of time in the past.

Version Control as a Safety Net

Version Control is a great way to "cover your bets". By keeping a record of all the changes, you've built up a complete history of all of the violence (er, editing) done to that file. Now how is this useful?

By keeping a history of your changes, you're keeping a record of all the work you've done. You have all of the good things you've tried so you can steal from them later. You also have all the bad things you've done, so you can avoid them later. You never know when the Past will provide something useful. Say you change an algorithm used in a piece of C source code. Two months later you decide that it is a stupid algorithm and you want to go back to the original. Or, someone discovers a programming error in an old version of your product and is willing to pay you for a patch. You can get the body of source code that made up that older version, make the change, and give your customer a patch. Without version control, performing these actions would be difficult, if not impossible.

Version control can also be another form of backing up your work. (you do regularly back up your work, don't you?) If all of your files are under version control and you regularly commit your changes, a complete snapshot of your work exists in a different location (whether it's on the same machine or via a server). If you blow away your work tree or a Perl script runs rampant, you can just delete your work tree can retreive the latest versions.

Version Control as a Commuications Medium

All version control systems allow you to comment on changes. When you make a change and commit it, you can include some text that tells what the change is and why it was made. Through the history of the file, you can glean all sorts of information about the file's status and health. If you see a lot of "fixed bug XYZ" or "fixed bone-head error ABC", you know that whomever is mainting the code is probably sloppy and error-prone, so you know to keep an eye on it.

Coupled with a ticket tracking machanism, version control (with decent check in comments) can be a tremendous asset when tracking down problems quickly or getting a new team member up to speed on a project.

If version control revision numbers are included in a problem ticket's resolution notes, someone later can view the ticket and know what the affected files were. How is this useful? If you know that Bob fixed a problem but didn't fix it right, you know what files were changed so you can un-do the damage. Or, if something is breaking in production, you can look at tickets that relate to the broken area of the system, see what was fixed recently, then use the revision information to track down who made what change. If ticket tracker numbers are included in version control check-in comments, you have even more information at your disposal. You'll be able to back-track to the ticket, see the explanation of the problem and cure, and see what was affected in the fix.

Making Version Control not work for you

Version Control is many a wonderful thing, but it's easy to make it not work for you. If you don't use it all, you obviously won't reap any of its benefits. If you don't add good comments when you commit your changes, the history mechanism becomes worthless. If you only perform very rare "big bang" check-ins of your work, you'll lose the back-up safety net described above, as well as making the differences between old versions of the file too great to effectively deal with.

The best way to use version control so that you have a good history and good communication is to do more small, incremental commits of your work rather than a few giant ones.
$Id: introduction.html,v 1.3 1999/12/23 23:09:10 markd Exp $