Bookreview: Pragmatic Version Control Using Subversion

review written by Gabor Szabo on 2005.04.26

This book is the first part of a series of three books from Pragmatic Bookshelf that also includes Pragmatic Unit Testing and Pragmatic Automation. While I have not seen those other books yet I think this is a very important subject that most of the programmers coming out from universities never heard of. I think it is very important that people will learn about these concepts early in their careers as these are basic tools in the craft of software development.

The Pragmatic Version Control Using Subversion while can be used as an introduction to Subversion only, it also fits people who don't have any experience with Version Control. While many programmers will say we are just programmers and only the Configuration Management group need to know this stuff I think reading this book will benefit both the programmers and the organization where they work.

In the first chapter the book start with a story about Fred and Wilma showing why version control even in small teams is very important.
Giving the almost standard reasons why to chose Subversion is probably not that necessary, after all the reader is already reading a book about SVN but it does not hurt either. Actually it is quite reassuring to read that you made the right choice in your Version Control system.

Chapter 2 - What Is Version Control? provides an overview of, well what Version Control is. It defines the terminology used in this book. Though it warns of misunderstanding that can be caused by terminology used by others, unfortunately there is no attempt to fill the gap and explain how the words from various terminologies are related.
It is also suggested that Subversion is good for off-line work and synchronization but actually for such task one would be better off using SVK.

Chapter 3 - Getting Started with Subversion is where the real work starts. In this chapter you learn how to setup a local repository and how to execute subversion commands to do your daily job. For this you learn how to import a directory structure, how to checkout, commit files and how to resolve conflicts when they arise on parallel development.
In my opinion it would have been clearer if the two changes creating a conflict were executed by two separate users but it was still a good explanation of the process and it was important to read it early in the book.

Chapter 4 - How To... is a short one that points out the two main reasons groups don't use version control:

• Lack of knowledge on how to use it
• Bad experience with overly complicated systems in terms of workflow
• ... and too complicated tools, I would add

The whole book is about addressing these issues.

Chapter 5 - Accessing a Repository covers the available options to setup a real networked Subversion with capability to handle multiple users. It provides some guidance as to when to choose which options. While a regular Subversion user might not need this information it's worth reading to understand the backend of such system. Besides, to learn more complex operations it is better to have multiple users in a distributed environment.

Chapter 6 - Common Subversion Commands is a long one and to tell the truth, I did not like it. Instead of keeping the theme that was used in the first part of the book, in this chapter we see examples using a number of themes which is slightly confusing. It is also too long and mostly just a set of examples without much connection among them. It does explain the various tasks and give examples but it would have been much better if it were split up into several shorter chapters and if it followed and expanded the original story.

Chapter 7 - Organizing Your Repository gives an overview of the two main layout options with some pro and contra reasoning.

Chapter 8 - Using Tags and Branches is about all this and of course about merge. Without that branching would just be useless. It provides an explanation of what these are and suggests "best practices" with several branching strategies. Personally I think the PRE and POST bug fix tags are a bit too extensive tagging but it is a legitimate one anyway.

Chapters 9-10
The remaining two chapters are actually already closer to Configuration Management than plain version control. This shows that the book (and probably the series of the 3 books) have the more global view of The Right Way to Software Development than just focusing on the use of Subversion.

Chapter 9 - Creating a Project. Here you can read about directory layout and why it is important to have a README file in the top-most directory of the project. It also explains code sharing between projects on the source code level, with or without the svn:externals property.

Chapter 10 - Third-Party code gives the reader a good introduction on how to deal with various situations involving either binary code or source code or both. It also shows how to deal with changes in third-party code on the administration level.

Appendix A - Install, Network, Secure, and Administer Subversion gives you a more detailed series of instructions on how to install a Subversion server with either way of networking it. It also helps you with the security considerations and with mundane tasks such as backup.

Actually there is a small bug in backup script on page 166. The weekly backup, after retrieving the number of the youngest revision dumps the whole repository. In the slight chance that someone commits a change exactly between these two operations will cause the script on the next day to include a change in the incremental backup that was already included once.
This is what can happen:

1. $youngest = `svnlook youngest $svn_reposs`; # in our backup script retrieves 10
2. # other task commits change 11
3. `svnadmin dump $svn_repos > dump`; # in our backup script dumps 0-11

Next day the incremental backup will dump from 11 to the youngest that day. Which means revision 11 is included both in the original backup and the incremental backup.
The solution could be to limit the original backup to the youngest as retrieved earlier in the script:

1. `svnadmin dump --revision 0:$youngest $svn_repos > dump`; # dumps 0-10

• Appendix B - Migrating to Subversion provides you with information on how to migrate from CVS to Subversion, more or less the same that you can read in the manual of cvs2svn.
• Appendix C - Third-Party Subversion Tools basically talks only about TortoiseSVN, which is Microsoft Windows only GUI client.
• Appendix D - Command Summary and Recipes in the first part gives some more details on commands that the command-line help but the more useful thing is the second part where you can see a bunch of recipes on thing such as Finding out where a working copy came from
• Appendix E - Other Resources are well, other resources.

Some other reviews of this book:

• by Mike Riley
• by Mike Gunderloy (Larkware)
• by Dean Wilson on Slashdot
• by Aaron Junod

Check out also the beginning of my RapidSVN user manual

Self advertising: I provide Subversion training, installation and support mainly in Israel though I am ready to travel to Europe and the US as well.