Ben Collins-Sussman

PDFR81 | Subversion is a free/open-source version control system (VCS). That is, Subversion manages files and directories, and the changes made to them, over time. This allows you to recover older versions of your data, or examine the history of how your data changed. In this regard, many people think of a version control system as a sort of “time machine.” Subversion can operate across networks, which allows it to be used by people on different computers. At some level, the ability of various people to modify and manage the same set of data from their respective locations fosters collaboration. Progress can occur more quickly without a single conduit through which all modifications must occur. And because the work is versioned, you need not fear that quality is the trade-off for losing that conduit—if some incorrect change is made to the data, just undo that change. Some version control systems are also software configuration management (SCM) systems. These systems are specifically tailored to manage trees of source code and have many features that are specific to software development—such as natively understanding programming languages, or supplying tools for building software. Subversion, however, is not one of these systems. It is a general system that can be used to manage any collection of files. For you, those files might be source code—for others, anything from grocery shopping lists to digital video mixdowns and beyond |

Contents
Foreword................................. xi
Preface .................................... xiii
What Is Subversion? ............................ xiii
Is Subversion the Right Tool? ........................................... xiii
Subversion's History ............................................ xiv
Subversion's Architecture ........................ xv
Subversion's Components ................................................ xvii
What's New in Subversion ........................... xvii
Audience .............................................. xviii
How to Read This Book ............... xix
Organization of This Book ......... xx
This Book Is Free .................................. xxi
Acknowledgments ............. xxi
1. Fundamental Concepts ......................................................................................................................................... 1
Version Control Basics .................................................................................................................................... 1
The Repository ...................................................................................................................................... 1
The Working Copy ................................................................................................................................. 2
Versioning Models ................................................................................................................................. 2
Version Control the Subversion Way ................................................................................................................. 7
Subversion Repositories ........................................................................................................................... 7
Revisions .............................................................................................................................................. 7
Addressing the Repository ....................................................................................................................... 8
Subversion Working Copies ..................................................................................................................... 9
Summary ..................................................................................................................................................... 14
2. Basic Usage ..................................................................................................................................................... 15
Help! .......................................................................................................................................................... 15
Getting Data into Your Repository .................................................................................................................. 16
Importing Files and Directories ............................................................................................................... 16
Recommended Repository Layout ........................................................................................................... 17
What's In a Name? ............................................................................................................................... 17
Creating a Working Copy .............................................................................................................................. 18
Basic Work Cycle ......................................................................................................................................... 19
Update Your Working Copy ................................................................................................................... 20
Make Your Changes .............................................................................................................................. 20
Review Your Changes ........................................................................................................................... 21
Fix Your Mistakes ................................................................................................................................ 25
Resolve Any Conflicts ........................................................................................................................... 26
Commit Your Changes .......................................................................................................................... 32
Examining History ........................................................................................................................................ 33
Examining the Details of Historical Changes ............................................................................................. 34
Generating a List of Historical Changes ................................................................................................... 35
Browsing the Repository ........................................................................................................................ 37
Fetching Older Repository Snapshots ....................................................................................................... 39
Sometimes You Just Need to Clean Up ............................................................................................................ 40
Disposing of a Working Copy ................................................................................................................ 40
Recovering from an Interruption ............................................................................................................. 40
Dealing with Structural Conflicts ..................................................................................................................... 41
An Example Tree Conflict ..................................................................................................................... 42
Summary ..................................................................................................................................................... 46
3. Advanced Topics .............................................................................................................................................. 47
Revision Specifiers ....................................................................................................................................... 47
Revision Keywords ............................................................................................................................... 47
Revision Dates ..................................................................................................................................... 48
Peg and Operative Revisions .......................................................................................................................... 49
Properties .................................................................................................................................................... 53
Why Properties? ................................................................................................................................... 54
Manipulating Properties ......................................................................................................................... 55
Properties and the Subversion Workflow .................................................................................................. 58
Automatic Property Setting ..................................................................................................................... 60
File Portability ............................................................................................................................................. 60
File Content Type ................................................................................................................................. 61
File Executability .................................................................................................................................. 62
End-of-Line Character Sequences ............................................................................................................ 62
Ignoring Unversioned Items ............................................................................................................................ 63
Keyword Substitution .................................................................................................................................... 66
Sparse Directories ......................................................................................................................................... 70
Locking ....................................................................................................................................................... 74
Creating Locks ..................................................................................................................................... 75
Discovering Locks ................................................................................................................................ 77
Breaking and Stealing Locks .................................................................................................................. 78
Lock Communication ............................................................................................................................ 80
Externals Definitions ..................................................................................................................................... 81
Changelists .................................................................................................................................................. 86
Creating and Modifying Changelists ........................................................................................................ 87
Changelists As Operation Filters ............................................................................................................. 89
Changelist Limitations ........................................................................................................................... 90
Network Model ............................................................................................................................................ 90
Requests and Responses ......................................................................................................................... 91
Client Credentials ................................................................................................................................. 91
Summary ..................................................................................................................................................... 94
4. Branching and Merging ...................................................................................................................................... 95
What's a Branch? .......................................................................................................................................... 95
Using Branches ............................................................................................................................................ 95
Creating a Branch ................................................................................................................................. 97
Working with Your Branch .................................................................................................................... 98
The Key Concepts Behind Branching ..................................................................................................... 101
Basic Merging ............................................................................................................................................ 101
Changesets ......................................................................................................................................... 101
Keeping a Branch in Sync .................................................................................................................... 102
Subtree Merges and Subtree Mergeinfo .................................................................................................. 105
Reintegrating a Branch ......................................................................................................................... 107
Mergeinfo and Previews ....................................................................................................................... 109
Undoing Changes ................................................................................................................................ 113
Resurrecting Deleted Items ................................................................................................................... 114
Advanced Merging ...................................................................................................................................... 115
Cherrypicking ..................................................................................................................................... 115
Merge Syntax: Full Disclosure .............................................................................................................. 117
Merges Without Mergeinfo ................................................................................................................... 118
More on Merge Conflicts ..................................................................................................................... 119
Blocking Changes ............................................................................................................................... 121
Keeping a Reintegrated Branch Alive ..................................................................................................... 122
Merge-Sensitive Logs and Annotations ................................................................................................... 123
Noticing or Ignoring Ancestry ............................................................................................................... 125
Merges and Moves .............................................................................................................................. 126
Preventing Naïve Clients from Committing Merges .................................................................................. 126
The Final Word on Merge Tracking ....................................................................................................... 127
Traversing Branches .................................................................................................................................... 128
Tags .......................................................................................................................................................... 129
Creating a Simple Tag ......................................................................................................................... 130
Creating a Complex Tag ...................................................................................................................... 130
Branch Maintenance .................................................................................................................................... 131
Repository Layout ............................................................................................................................... 131
Data Lifetimes .................................................................................................................................... 132
Common Branching Patterns ......................................................................................................................... 132
Release Branches ................................................................................................................................ 133
Feature Branches ................................................................................................................................. 133
Vendor Branches ......................................................................................................................................... 134
General Vendor Branch Management Procedure ....................................................................................... 135
svn_load_dirs.pl .................................................................................................................................. 136
To Branch or Not to Branch? ........................................................................................................................ 137
Summary ................................................................................................................................................... 138
5. Repository Administration ................................................................................................................................. 140
The Subversion Repository, Defined .............................................................................................................. 140
Strategies for Repository Deployment ............................................................................................................. 141
Planning Your Repository Organization .................................................................................................. 141
Deciding Where and How to Host Your Repository .................................................................................. 143
Choosing a Data Store ......................................................................................................................... 144
Creating and Configuring Your Repository ...................................................................................................... 146
Creating the Repository ........................................................................................................................ 147
Implementing Repository Hooks ............................................................................................................ 147
Berkeley DB Configuration .................................................................................................................. 149
FSFS Configuration ............................................................................................................................. 149
Repository Maintenance ............................................................................................................................... 149
An Administrator's Toolkit ................................................................................................................... 149
Commit Log Message Correction ........................................................................................................... 153
Managing Disk Space .......................................................................................................................... 153
Berkeley DB Recovery ........................................................................................................................ 157
Migrating Repository Data Elsewhere ..................................................................................................... 158
Filtering Repository History .................................................................................................................. 162
Repository Replication ......................................................................................................................... 165
Repository Backup .............................................................................................................................. 171
Managing Repository UUIDs ................................................................................................................ 173
Moving and Removing Repositories ............................................................................................................... 174
Summary ................................................................................................................................................... 174
6. Server Configuration ........................................................................................................................................ 175
Overview ................................................................................................................................................... 175
Choosing a Server Configuration ................................................................................................................... 176
The svnserve Server ............................................................................................................................ 176
svnserve over SSH .............................................................................................................................. 176
The Apache HTTP Server .................................................................................................................... 177
Recommendations ............................................................................................................................... 177
svnserve, a Custom Server ............................................................................................................................ 178
Invoking the Server ............................................................................................................................. 178
Built-in Authentication and Authorization ............................................................................................... 182
Using svnserve with SASL .................................................................................................................. 184
Tunneling over SSH ............................................................................................................................ 186
SSH Configuration Tricks ..................................................................................................................... 187
httpd, the Apache HTTP Server ..................................................................................................................... 188
Prerequisites ....................................................................................................................................... 189
Basic Apache Configuration .................................................................................................................. 189
Authentication Options ......................................................................................................................... 191
Authorization Options .......................................................................................................................... 194
Protecting network traffic with SSL ....................................................................................................... 197
Extra Goodies ..................................................................................................................................... 199
Path-Based Authorization ............................................................................................................................. 206
High-level Logging ..................................................................................................................................... 210
Server Optimization ..................................................................................................................................... 212
Data Caching ...................................................................................................................................... 212
Network Compression of Data .............................................................................................................. 213
Supporting Multiple Repository Access Methods .............................................................................................. 213
7. Customizing Your Subversion Experience ........................................................................................................... 215
Runtime Configuration Area ......................................................................................................................... 215
Configuration Area Layout ................................................................................................................... 215
Configuration and the Windows Registry ................................................................................................ 216
Configuration Options .......................................................................................................................... 217
Localization ............................................................................................................................................... 223
Understanding Locales ......................................................................................................................... 223
Subversion's Use of Locales ................................................................................................................. 224
Using External Editors ................................................................................................................................. 225
Using External Differencing and Merge Tools ................................................................................................. 226
External diff ....................................................................................................................................... 226
External diff3 ..................................................................................................................................... 227
External merge ................................................................................................................................... 229
Summary ................................................................................................................................................... 230
8. Embedding Subversion ..................................................................................................................................... 231
Layered Library Design ............................................................................................................................... 231
Repository Layer ................................................................................................................................. 232
Repository Access Layer ...................................................................................................................... 235
Client Layer ....................................................................................................................................... 236
Using the APIs ........................................................................................................................................... 237
The Apache Portable Runtime Library .................................................................................................... 237
Functions and Batons ........................................................................................................................... 238
URL and Path Requirements ................................................................................................................. 238
Using Languages Other Than C and C ................................................................................................ 239
Code Samples ..................................................................................................................................... 240
Summary ................................................................................................................................................... 245
9. Subversion Complete Reference ......................................................................................................................... 247
svn—Subversion Command-Line Client .......................................................................................................... 247
svn Options ........................................................................................................................................ 247
svn Subcommands ............................................................................................................................... 255
svnadmin—Subversion Repository Administration ............................................................................................ 329
svnadmin Options ............................................................................................................................... 329
svnadmin Subcommands ...................................................................................................................... 331
svnlook—Subversion Repository Examination ................................................................................................. 352
svnlook Options .................................................................................................................................. 352
svnlook Subcommands ......................................................................................................................... 354
svnsync—Subversion Repository Mirroring ..................................................................................................... 374
svnsync Options .................................................................................................................................. 374
svnsync Subcommands ......................................................................................................................... 376
svnrdump—Remote Subversion Repository Data Migration ................................................................................ 384
svnrdump Options ............................................................................................................................... 384
svnrdump Subcommands ...................................................................................................................... 385
svnserve—Custom Subversion Server ............................................................................................................. 388
svnserve Options ................................................................................................................................. 389
svndumpfilter—Subversion History Filtering ................................................................................................... 390
svndumpfilter Options .......................................................................................................................... 390
svndumpfilter Subcommands ................................................................................................................. 391
svnversion—Subversion Working Copy Version Info ........................................................................................ 396
mod_dav_svn—Subversion Apache HTTP Server Module ................................................................................. 398
mod_authz_svn—Subversion Apache HTTP Authorization Module ..................................................................... 401
Subversion Properties .................................................................................................................................. 402
Versioned Properties ............................................................................................................................ 402
Unversioned Properties ........................................................................................................................ 403
Repository Hooks ........................................................................................................................................ 404
A. Subversion Quick-Start Guide ........................................................................................................................... 414
Installing Subversion ................................................................................................................................... 414
High-Speed Tutorial .................................................................................................................................... 414
B. Subversion for CVS Users ................................................................................................................................ 417
Revision Numbers Are Different Now ............................................................................................................ 417
Directory Versions ...................................................................................................................................... 417
More Disconnected Operations ...................................................................................................................... 418
Distinction Between Status and Update ........................................................................................................... 418
Status ................................................................................................................................................ 418
Update ............................................................................................................................................... 419
Branches and Tags ...................................................................................................................................... 419
Metadata Properties ..................................................................................................................................... 420
Conflict Resolution ...................................................................................................................................... 420
Binary Files and Translation ......................................................................................................................... 420
Versioned Modules ...................................................................................................................................... 420
Authentication ............................................................................................................................................ 421
Converting a Repository from CVS to Subversion ............................................................................................ 421
C. WebDAV and Autoversioning ........................................................................................................................... 422
What Is WebDAV? ..................................................................................................................................... 422
Autoversioning ........................................................................................................................................... 423
Client Interoperability .................................................................................................................................. 424
Standalone WebDAV Applications ......................................................................................................... 425
File-Explorer WebDAV Extensions ........................................................................................................ 426
WebDAV Filesystem Implementation ..................................................................................................... 427
D. Copyright ...................................................................................................................................................... 429
Index ................................................................................................................................................................. 435

List of Figures
1. Subversion's architecture ................................................................................................................................... xvi
1.1. A typical client/server system ............................................................................................................................. 1
1.2. The problem to avoid ....................................................................................................................................... 3
1.3. The lock-modify-unlock solution ........................................................................................................................ 4
1.4. The copy-modify-merge solution ........................................................................................................................ 5
1.5. The copy-modify-merge solution (continued) ........................................................................................................ 6
1.6. Tree changes over time ..................................................................................................................................... 8
1.7. The repository's filesystem ............................................................................................................................... 11
4.1. Branches of development ................................................................................................................................. 95
4.2. Starting repository layout ................................................................................................................................. 96
4.3. Repository with new copy ................................................................................................................................ 98
4.4. The branching of one file's history .................................................................................................................... 99
8.1. Files and directories in two dimensions ............................................................................................................ 234
8.2. Versioning time—the third dimension! ............................................................................................................. 234

Links
http://www.gnome.org/ | http://www.kde.org/ | http://www.ics.uci.edu/~webdav/ | http://www.webdav.org/cadaver/ | http://cvs2svn.tigris.org/ | http://svn.apache.org/repos/asf/subversion | http://subversion.apache.org/ | http://mercurial.selenic.com/ | http://git-scm.com/ | http://www.collab.net/ |

SA - Repository Administration | https://svnbook.red-bean.com/ |
RT - Software
BT - Software Configuration Management SCM
NT - Version Control System VCS
UF - File, Directory Management
SN - This is a book about managing the actual repository with data sets. (This entry does not reference a hierarchical list)… (plus d'informations)