Version Control with Subversion

For Subversion 1.1

(book compiled from Revision 1337)

Ben Collins-Sussman

Brian W. Fitzpatrick

C. Michael Pilato

Version Control with Subversion: For Subversion 1.1: (book compiled from Revision 1337)

by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato

Published (TBA)

Copyright © 2002, 2003, 2004, 2005 Ben Collins-SussmanBrian W. FitzpatrickC. Michael Pilato

This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

Table of Contents
Foreword ......................................................................................................................................	11
Preface .........................................................................................................................................	13
Audience ..............................................................................................................................	13
How to Read this Book ...........................................................................................................	13
Conventions Used in This Book ................................................................................................	14
Typographic Conventions ................................................................................................	14
Icons ...........................................................................................................................	14
Organization of This Book .......................................................................................................	15
New in Subversion 1.1 ............................................................................................................	16
This Book is Free ...................................................................................................................	17
Acknowledgments ..................................................................................................................	17
From Ben Collins-Sussman ..............................................................................................	17
From Brian W. Fitzpatrick ...............................................................................................	18
From C. Michael Pilato ...................................................................................................	18
1. Introduction ...............................................................................................................................	1
What is Subversion? ...............................................................................................................	1
Subversion's History ...............................................................................................................	1
Subversion's Features ..............................................................................................................	2
Subversion's Architecture ........................................................................................................	3
Installing Subversion ..............................................................................................................	4
Subversion's Components ........................................................................................................	5
A Quick Start ........................................................................................................................	5
2. Basic Concepts ...........................................................................................................................	8
The Repository ......................................................................................................................	8
Versioning Models .................................................................................................................	8
The Problem of File-Sharing ............................................................................................	9
The Lock-Modify-Unlock Solution ....................................................................................	9
The Copy-Modify-Merge Solution ....................................................................................	11
Subversion in Action ..............................................................................................................	12
Working Copies .............................................................................................................	13
Revisions ......................................................................................................................	15
How Working Copies Track the Repository ........................................................................	17
The Limitations of Mixed Revisions ..................................................................................	18
Summary ..............................................................................................................................	18
3. Guided Tour ..............................................................................................................................	19
Help! ...................................................................................................................................	19
Import ..................................................................................................................................	19
Revisions: Numbers, Keywords, and Dates, Oh My! .....................................................................	19
Revision Numbers ..........................................................................................................	19
Revision Keywords ........................................................................................................	19
Revision Dates ..............................................................................................................	20
Initial Checkout .....................................................................................................................	22
Basic Work Cycle ..................................................................................................................	23
Update Your Working Copy .............................................................................................	24
Make Changes to Your Working Copy ...............................................................................	24
Examine Your Changes ...................................................................................................	26
Resolve Conflicts (Merging Others' Changes) ......................................................................	31
Commit Your Changes ....................................................................................................	34
Examining History .................................................................................................................	35
svn log .........................................................................................................................	35
svn diff ........................................................................................................................	37
svn cat .........................................................................................................................	38
svn list .........................................................................................................................	39
iv

Version Control with Subversion
A Final Word on History .................................................................................................	39
Other Useful Commands .........................................................................................................	39
svn cleanup ...................................................................................................................	40
svn import ....................................................................................................................	40
Summary ..............................................................................................................................	40
4. Branching and Merging ...............................................................................................................	42
What's a Branch? ...................................................................................................................	42
Using Branches .....................................................................................................................	42
Creating a Branch ..........................................................................................................	44
Working with Your Branch ..............................................................................................	46
The Key Concepts Behind Branches ..................................................................................	48
Copying Changes Between Branches .........................................................................................	48
Copying Specific Changes ...............................................................................................	48
The Key Concept Behind Merging ....................................................................................	51
Best Practices for Merging ...............................................................................................	51
Common Use-Cases ...............................................................................................................	54
Merging a Whole Branch to Another ..................................................................................	54
Undoing Changes ...........................................................................................................	56
Resurrecting Deleted Items ..............................................................................................	57
Common Branching Patterns ............................................................................................	58
Switching a Working Copy ......................................................................................................	60
Tags ....................................................................................................................................	61
Creating a Simple Tag .....................................................................................................	61
Creating a Complex Tag ..................................................................................................	62
Branch Maintenance ...............................................................................................................	63
Repository Layout ..........................................................................................................	63
Data Lifetimes ...............................................................................................................	63
Summary ..............................................................................................................................	64
5. Repository Administration ............................................................................................................	65
Repository Basics ...................................................................................................................	65
Understanding Transactions and Revisions ..........................................................................	65
Unversioned Properties ...................................................................................................	66
Repository Data-Stores ...................................................................................................	66
Repository Creation and Configuration .......................................................................................	68
Hook Scripts .................................................................................................................	70
Berkeley DB Configuration ..............................................................................................	72
Repository Maintenance ..........................................................................................................	72
An Administrator's Toolkit ...............................................................................................	72
Repository Cleanup ........................................................................................................	81
Managing Disk Space .....................................................................................................	83
Repository Recovery ......................................................................................................	84
Migrating a Repository ....................................................................................................	85
Repository Backup .........................................................................................................	88
Adding Projects .....................................................................................................................	89
Choosing a Repository Layout ..........................................................................................	90
Creating the Layout, and Importing Initial Data ...................................................................	91
Summary ..............................................................................................................................	92
6. Server Configuration ...................................................................................................................	93
Overview ..............................................................................................................................	93
Network Model .....................................................................................................................	94
Requests and Responses ..................................................................................................	94
Client Credentials Caching ...............................................................................................	94
svnserve, a custom server ........................................................................................................	96
Invoking the Server ........................................................................................................	96
Built-in authentication and authorization .............................................................................	97
SSH authentication and authorization .................................................................................	99
SSH configuration tricks ..................................................................................................	101
httpd, the Apache HTTP server .................................................................................................	102

v

Version Control with Subversion
Prerequisites .................................................................................................................	103
Basic Apache Configuration .............................................................................................	103
Authentication Options ...................................................................................................	105
Authorization Options .....................................................................................................	108
Extra Goodies ................................................................................................................	113
Supporting Multiple Repository Access Methods .........................................................................	114
7. Advanced Topics ........................................................................................................................	116
Runtime Configuration Area ....................................................................................................	116
Configuration Area Layout ..............................................................................................	116
Configuration and the Windows Registry ............................................................................	117
Configuration Options .....................................................................................................	118
Properties .............................................................................................................................	121
Why Properties? ............................................................................................................	122
Manipulating Properties ..................................................................................................	122
Special Properties ...........................................................................................................	126
Automatic Property Setting ..............................................................................................	132
Peg and Operative Revisions ....................................................................................................	132
Externals Definitions ..............................................................................................................	135
Vendor branches ....................................................................................................................	136
General Vendor Branch Management Procedure ..................................................................	137
svn_load_dirs.pl .............................................................................................................	138
Localization ..........................................................................................................................	139
Understanding locales .....................................................................................................	140
Subversion's use of locales ...............................................................................................	140
Subversion Repository URLs ...................................................................................................	141
8. Developer Information .................................................................................................................	143
Layered Library Design ...........................................................................................................	143
Repository Layer ...........................................................................................................	144
Repository Access Layer .................................................................................................	148
Client Layer ..................................................................................................................	150
Using the APIs ......................................................................................................................	151
The Apache Portable Runtime Library ...............................................................................	151
URL and Path Requirements ............................................................................................	152
Using Languages Other than C and C++ .............................................................................	152
Inside the Working Copy Administration Area .............................................................................	154
The Entries File .............................................................................................................	154
Pristine Copies and Property Files .....................................................................................	155
WebDAV .............................................................................................................................	156
Programming with Memory Pools .............................................................................................	156
Contributing to Subversion ......................................................................................................	158
Join the Community .......................................................................................................	158
Get the Source Code .......................................................................................................	159
Become Familiar with Community Policies .........................................................................	159
Make and Test Your Changes ...........................................................................................	160
Donate Your Changes .....................................................................................................	160
9. Subversion Complete Reference ....................................................................................................	161
The Subversion Command Line Client: svn .................................................................................	161
svn Switches .................................................................................................................	161
svn Subcommands ..........................................................................................................	164
svnadmin ..............................................................................................................................	222
svnadmin Switches .........................................................................................................	222
svnadmin Subcommands .................................................................................................	223
svnlook ................................................................................................................................	236
svnlook Switches ...........................................................................................................	236
svnlook ........................................................................................................................	237
svnserve ...............................................................................................................................	252
svnserve Switches ..........................................................................................................	252
svnversion ............................................................................................................................	253

vi

Version Control with Subversion
mod_dav_svn ........................................................................................................................	255
A. Subversion for CVS Users ...........................................................................................................	257
Revision Numbers Are Different Now ........................................................................................	257
Directory Versions .................................................................................................................	257
More Disconnected Operations .................................................................................................	258
Distinction Between Status and Update ......................................................................................	258
Branches and Tags .................................................................................................................	259
Metadata Properties ................................................................................................................	260
Conflict Resolution ................................................................................................................	260
Binary Files and Translation .....................................................................................................	260
Versioned Modules ................................................................................................................	260
Authentication .......................................................................................................................	261
Converting a Repository from CVS to Subversion ........................................................................	261
B. Troubleshooting .........................................................................................................................	262
Common Problems .................................................................................................................	262
Problems Using Subversion .............................................................................................	262
C. WebDAV and Autoversioning ......................................................................................................	268
Basic WebDAV Concepts ........................................................................................................	268
Just Plain WebDAV .......................................................................................................	268
DeltaV Extensions ..........................................................................................................	268
Subversion and DeltaV ............................................................................................................	269
Mapping Subversion to DeltaV .........................................................................................	270
Autoversioning Support ...................................................................................................	270
The mod_dav_lock Alternative .........................................................................................	271
Autoversioning Interoperability ................................................................................................	271
Win32 WebFolders ........................................................................................................	272
Mac OS X ....................................................................................................................	272
Unix: Nautilus 2 ............................................................................................................	272
Linux davfs2 .................................................................................................................	273
D. Third Party Tools .......................................................................................................................	274
Clients and Plugins .................................................................................................................	274
Language Bindings .................................................................................................................	274
Repository Converters .............................................................................................................	275
Higher Level Tools .................................................................................................................	275
Repository Browsing Tools ......................................................................................................	275
E. Copyright .................................................................................................................................	277

vii

List of Figures
1.1. Subversion's Architecture ..........................................................................................................	3
2.1. A typical client/server system .....................................................................................................	8
2.2. The problem to avoid ................................................................................................................	9
2.3. The lock-modify-unlock solution .................................................................................................	10
2.4. The copy-modify-merge solution .................................................................................................	11
2.5. The copy-modify-merge solution (continued) ................................................................................	12
2.6. The repository's filesystem .........................................................................................................	13
2.7. The repository .........................................................................................................................	16
4.1. Branches of development ...........................................................................................................	42
4.2. Starting repository layout ...........................................................................................................	43
4.3. Repository with new copy ..........................................................................................................	45
4.4. The branching of one file's history ...............................................................................................	46
8.1. Files and directories in two dimensions .........................................................................................	145
8.2. Versioning time—the third dimension! .........................................................................................	145

viii

List of Tables
2.1. Repository Access URLs ...........................................................................................................	15
5.1. Repository Data-Store Comparison ..............................................................................................	66
6.1. Network Server Comparison .......................................................................................................	93
8.1. A Brief Inventory of the Subversion Libraries ................................................................................	143

ix

List of Examples
5.1. Using svnshell to Navigate the Repository ....................................................................................	80
5.2. txn-info.sh (Reporting Outstanding Transactions) ...........................................................................	82
6.1. A sample configuration for anonymous access. ..............................................................................	109
6.2. A sample configuration for authenticated access. ............................................................................	110
6.3. A sample configuration for mixed authenticated/anonymous access. ..................................................	110
6.4. Disabling path checks altogether .................................................................................................	112
7.1. Sample Registration Entries (.reg) File. ........................................................................................	117
8.1. Using the Repository Layer ........................................................................................................	146
8.2. Using the Repository Layer with Python .......................................................................................	152
8.3. A Simple Script to Check Out a Working Copy. .............................................................................	153
8.4. Contents of a Typical .svn/entries File ..........................................................................................	154
8.5. Effective Pool Usage .................................................................................................................	157

x