# Preface

> If C gives you enough rope to hang yourself, think of Subversion as a sort of rope storage facility. —Brian W. Fitzpatrick

In the world of open-source software, the Concurrent Versions System (CVS) has long been the tool of choice for version control. And rightly so. CVS itself is free software, and its non-restrictive modus operandi and support for networked operation—which allow dozens of geographically dispersed programmers to share their work—fits the collaborative nature of the open-source world very well. CVS and its semi-chaotic development model have become cornerstones of open-source culture.

But like many tools, CVS is starting to show its age. Subversion is a relatively new version control system designed to be the successor to CVS. The designers set out to win the hearts of CVS users in two ways: by creating an open-source system with a design (and look and feel) similar to CVS, and by attempting to fix most of CVS's noticeable flaws. While the result isn't necessarily the next great evolution in version control design, Subversion is very powerful, very usable, and very flexible.

This book is written to document the 1.0 series of the Subversion version control system. We have made every attempt to be thorough in our coverage. However, Subversion has a thriving and energetic development community, so there are already a number of features and improvements planned for future versions of Subversion that may change some of the commands and specific notes in this book.

## Audience

This book is written for computer-literate folk who want to use Subversion to manage their data. While Subversion runs on a number of different operating systems, its primary user interface is command-line based. It is that command-line tool (`svn`) which is discussed and used in this book. For consistency, the examples in this book assume the reader is using a Unix-like operating system, and is relatively comfortable with Unix and command-line interfaces.

That said, the `svn` program also runs on non-Unix platforms like Microsoft Windows. With a few minor exceptions, such as the use of backward slashes (`\`) instead of forward slashes (`/`) for path separators, the input to and output from this tool when run on Windows are identical to its Unix counterpart. However, Windows users may find more success by running the examples inside the Cygwin Unix emulation environment.

Most readers are probably programmers or sysadmins who need to track changes to source code. This is the most common use for Subversion, and therefore it is the scenario underlying all of the book's examples. But Subversion can be used to manage changes to any sort of information: images, music, databases, documentation, and so on. To Subversion, all data is just data.

While this book is written with the assumption that the reader has never used version control, we've also tried to make it easy for users of CVS to make a painless leap into Subversion. Special sidebars may discuss CVS from time to time, and a special appendix summarizes most of the differences between CVS and Subversion.

## How to Read this Book

This book aims to be useful to people of widely different backgrounds—from people with no previous experience in version control to experienced sysadmins. Depending on your own background, certain chapters may be more or less important to you. The following can be considered a recommended reading list for various types of readers:

Experienced sysadmins

  The assumption here is that you've probably used CVS before, and are dying to get a Subversion server up and running ASAP. Chapters 5 and 6 will show you how to create your first repository and make it available over the network. After that's done, chapter 3 and appendix A are the fastest routes to learning the Subversion client while drawing on your CVS experience.

New users

  Your administrator has probably set up Subversion already, and you need to learn how to use the client. If you've never used a version control system (like CVS), then chapters 2 and 3 are a vital introduction. If you're already an old hand at CVS, chapter 3 and appendix A are the best place to start.

Advanced users

  Whether you're a user or administrator, eventually your project will grow larger. You're going to want to learn how to do more advanced things with Subversion, such as how to use branches and perform merges (chapter 4), how to use Subversion's property support, how to configure runtime options (chapter 7), and other things. Chapters 4 and 7 aren't vital at first, but be sure to read them once you're comfortable with the basics.

Developers

  Presumably, you're already familiar with Subversion, and now want to either extend it or build new software on top of its many APIs. Chapter 8 is just for you.

The book ends with reference material—chapter 9 is a reference guide for all Subversion commands, and the appendices cover a number of useful topics. These are the chapters you're mostly likely to come back to after you've finished the book.

## Conventions Used in This Book

This section covers the various conventions used in this book.

### Typographic Conventions

`Constant width`

  Used for commands, command output, and switches

Constant width italic

  Used for replaceable items in code and text

`Italic`

  Used for file and directory names

### Icons

This icon designates a note relating to the surrounding text.

This icon designates a helpful tip relating to the surrounding text.

This icon designates a warning relating to the surrounding text.

Note that the source code examples are just that—examples. While they will compile with the proper compiler incantations, they are intended to illustrate the problem at hand, not necessarily serve as examples of good programming style.

## Organization of This Book

The chapters that follow and their contents are listed here:

Chapter 1, Introduction

  Covers the history of Subversion as well as its features, architecture, components, and install methods. Also includes a quick-start guide.

Chapter 2, Basic Concepts

  Explains the basics of version control and different versioning models, along with Subversion's repository, working copies, and revisions.

Chapter 3, Guided Tour

  Walks you through a day in the life of a Subversion user. It demonstrates how to use Subversion to obtain, modify, and commit data.

Chapter 4, Branching and Merging

  Discusses branches, merges, and tagging, including best practices for branching and merging, common use-cases, how to undo changes, and how to easily swing from one branch to the next.

Chapter 5, Repository Administration

  Describes the basics of the Subversion repository, how to create, configure, and maintain a repository, and the tools you can use to do all of this.

Chapter 6, Server Configuration

  Explains how to configure your Subversion server and the three ways to access your repository: `HTTP`, the `svn` protocol, and local access. It also covers the details of authentication, authorization and anonymous access.

Chapter 7, Advanced Topics

  Explores the Subversion client configuration files, file and directory properties, how to `ignore` files in your working copy, how to include external trees in your working copy, and lastly, how to handle vendor branches.

Chapter 8, Developer Information

  Describes the internals of Subversion, the Subversion filesystem, and the working copy administrative areas from a programmer's point of view. Demonstrates how to use the public APIs to write a program that uses Subversion, and most importantly, how to contribute to the development of Subversion.

Chapter 9, Subversion Complete Reference

  Explains in great detail every subcommand of `svn`, `svnadmin`, and `svnlook` with plenty of examples for the whole family!

Appendix A, Subversion for CVS Users

  Covers the similarities and differences between Subversion and CVS, with numerous suggestions on how to break all the bad habits you picked up from years of using CVS. Included are descriptions of Subversion revision numbers, versioned directories, offline operations, `update` vs. `status`, branches, tags, metadata, conflict resolution, and authentication.

Appendix B, Troubleshooting

  Addresses common problems and difficulties using and building Subversion.

Appendix C, WebDAV and Autoversioning

  Describes the details of WebDAV and DeltaV, and how you can configure your Subversion repository to be mounted read/write as a DAV share.

Appendix D, Third Party Tools

  Discusses tools that support or use Subversion, including alternative client programs, repository browser tools, and so on.

## This Book is Free

This book started out as bits of documentation written by Subversion project developers, which were then coalesced into a single work and rewritten. As such, it has always been under a free license. (See .) In fact, the book was written in the public eye, as a part of Subversion. This means two things:

- You will always find the latest version of this book in Subversion's own source tree.

- You can distribute and make changes to this book however you wish—it's under a free license. Of course, rather than distribute your own private version of this book, we'd much rather you send feedback and patches to the Subversion developer community. See to learn about joining this community.

You can send publishing comments and questions to O'Reilly here: ###insert boilerplate.

A relatively recent online version of this book can be found at http://svnbook.red-bean.com.

## Acknowledgments

This book would not be possible (nor very useful) if Subversion did not exist. For that, the authors would like to thank Brian Behlendorf and CollabNet for the vision to fund such a risky and ambitious new Open Source project; Jim Blandy for the original Subversion name and design—we love you, Jim; Karl Fogel for being such a good friend and a great community leader, in that order. Oh, and thanks, Karl, for being too overworked to write this book yourself.

Thanks to O'Reilly and our editors, Linda Mui and Tatiana Diaz for their patience and support.

Finally, we thank the countless people who contributed to this book with informal reviews, suggestions, and fixes: While this is undoubtedly not a complete list, this book would be incomplete and incorrect without the help of: Jani Averbach, Ryan Barrett, Francois Beausoleil, Jennifer Bevan, Matt Blais, Zack Brown, Martin Buchholz, Brane Cibej, John R. Daily, Peter Davis, Olivier Davy, Robert P. J. Day, Mo DeJong, Brian Denny, Joe Drew, Nick Duffek, Ben Elliston, Justin Erenkrantz, Shlomi Fish, Julian Foad, Chris Foote, Martin Furter, Dave Gilbert, Eric Gillespie, Matthew Gregan, Art Haas, Greg Hudson, Alexis Huxley, Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark Benedetto King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai, Scott Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier, Bruce A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg, Gareth McCaughan, Jon Middleton, Tim Moloney, Mats Nilsson, Joe Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy Popkov, Michael Price, Mark Proctor, Steffen Prohaska, Daniel Rall, Tobias Ringstrom, Garrett Rooney, Joel Rosdahl, Christian Sauer, Larry Shatzer, Russell Steicke, Sander Striker, Erik Sjoelund, Johan Sundstroem, John Szakmeister, Mason Thomas, Eric Wadsworth, Colin Watson, Alex Waugh, Chad Whitacre, Josef Wolf, Blair Zajac, and the entire Subversion community.

### From Ben Collins-Sussman

Thanks to my wife Frances, who, for many months, got to hear, But honey, I'm still working on the book, rather than the usual, But honey, I'm still doing email. I don't know where she gets all that patience! She's my perfect counterbalance.

Thanks to my extended family for their sincere encouragement, despite having no actual interest in the subject. (You know, the ones who say, Ooh, you're writing a book?, and then when you tell them it's a computer book, sort of glaze over.)

Thanks to all my close friends, who make me a rich, rich man. Don't look at me that way—you know who you are.

### From Brian W. Fitzpatrick

Huge thanks to my wife Marie for being incredibly understanding, supportive, and most of all, patient. Thank you to my brother Eric who first introduced me to UNIX programming way back when. Thanks to my Mom and Grandmother for all their support, not to mention enduring a Christmas holiday where I came home and promptly buried my head in my laptop to work on the book.

To Mike and Ben: It was a pleasure working with you on the book. Heck, it's a pleasure working with you at work!

To everyone in the Subversion community and the Apache Software Foundation, thanks for having me. Not a day goes by where I don't learn something from at least one of you.

Lastly, thanks to my Grandfather who always told me that freedom equals responsibility. I couldn't agree more.

### From C. Michael Pilato

Special thanks to my wife, Amy, for her love and patient support, for putting up with late nights, and for even reviewing entire sections of this book—you always go the extra mile, and do so with incredible grace. Gavin, when you're old enough to read, I hope you're as proud of your Daddy as he is of you. Mom and Dad (and the rest of the family), thanks for your constant support and enthusiasm.

Hats off to Shep Kendall, through whom the world of computers was first opened to me; Ben Collins-Sussman, my tour-guide through the open-source world; Karl Fogel—you are my `.emacs`; Greg Stein, for oozing practical programming know-how; Brian Fitzpatrick—for sharing this writing experience with me. To the many folks from whom I am constantly picking up new knowledge—keep dropping it!

Finally, to the One who perfectly demonstrates creative excellence—thank you.