Version Control with Subversion

Draft

Ben Collins-Sussman

Brian W. Fitzpatrick

C. Michael Pilato

(TBA)


Table of Contents

Preface
Audience
How This Book is Organized
Conventions Used in This Book
This Book is Free
Acknowledgments
1. Introduction
What is Subversion?
Subversion's History
Subversion's Features
Installing Subversion
Subversion's Components
Client Components (for the User)
Server Components (for the Administrator)
2. Basic Concepts
The Repository
Versioning Models
The Problem of File-Sharing
The Lock-Modify-Unlock Solution
The Copy-Modify-Merge Solution
Subversion in Action
Working Copies
Revisions
How Working Copies Track the Repository
The Limitations of Mixed Revisions
Summary
3. Guided Tour
Help!
Import
Revisions: Numbers, Keywords, and Dates, Oh My!
Revision Numbers
Revision Keywords
Revision Dates
Initial Checkout
Basic Workcycle
Update Your Working Copy
Make Changes to Your Working Copy
Examine Your Changes
Resolving Conflicts (Merging Others' Changes)
Commit Your Changes
Examining History
svn log
svn diff
svn cat
svn list
A Final Word on History
Other Frequently Used Commands
svn cleanup
svn import
Summary
4. Branching and Merging
What's a Branch?
Using Branches
Creating a Branch
Working with Your Branch
The Moral of the Story
Copying Changes Between Branches
Copying Specific Changes
The Repeated Merge Problem
Merging an Entire Branch
Removing a Change from the Repository
Switching a Working Copy
Tags
Creating a Simple Tag
Creating a Complex Tag
Branch Maintenance
Repository Layout
Data Lifetimes
Summary
5. Repository Administration
Repository Basics
Understanding Transactions and Revisions
Unversioned Properties
Repository Creation and Configuration
Hook Scripts
Berkeley DB Configuration
Repository Maintenance
An Administrator's Toolkit
Repository Cleanup
Repository Recovery
Migrating a Repository
Repository Backup
Networking a Repository
httpd, the Apache HTTP Server
svnserve, a Custom Subversion Server
Which Server to Use?
Repository Permissions
Adding Projects
Choosing a Repository Layout
Creating the Layout, and Importing Initial Data
Summary
6. Advanced Topics
Runtime Configuration Area
Configuration Area Layout
Configuration and the Windows Registry
Configuration Options
Properties
Why Properties?
Manipulating Properties
Special properties
Externals Definitions
Vendor branches
General Vendor Branch Management Procedure
svn-load-dirs.pl
7. Developer Information
Layered Library Design
Repository Layer
Repository Access Layer
Client Layer
Using the APIs
The Apache Portable Runtime Library
URL and Path Requirements
Using Languages Other than C and C++
Inside the Working Copy Administration Area
The Entries File
Pristine Copies and Property Files
WebDAV
Programming with Memory Pools
Contributing to Subversion
Join the Community
Get the Source Code
Become Familiar with Community Policies
Make and Test Your Changes
Donate Your Changes
8. Subversion Complete Reference
The Subversion Command Line Client: svn
svn Switches
svn Subcommands
svnadmin
svnadmin Switches
svnadmin Subcommands
svnlook
svnlook Switches
svnlook Subcommands
A. Subversion for CVS Users
Revision Numbers Are Different Now
Directory Versions
More Disconnected Operations
Distinction Between Status and Update
Branches and Tags
Meta-data Properties
Conflict Resolution
Binary Files and Translation
Versioned Modules
B. CVS Repository Migration
Requirements
Running cvs2svn.py
C. Troubleshooting
Common Problems
Problems Using Subversion
Problems Building Subversion
D. WebDAV and Autoversioning
Basic WebDAV Concepts
Just Plain WebDAV
DeltaV Extensions
Subversion and DeltaV
Mapping Subversion to DeltaV
Autoversioning Support
The mod_dav_lock Alternative
Autoversioning Interoperability
Win32 WebFolders
Mac OS X
Unix: Nautilus 2
Linux davfs2
E. Other Subversion Clients
Out of One, Many
F. Third Party Tools
ViewCVS
SubWiki
Glossary

List of Figures

2.1. A Typical Client/Server System
2.2. The Problem to Avoid
2.3. The Lock-Modify-Unlock Solution
2.4. The Copy-Modify-Merge Solution
2.5. …Copy-Modify-Merge Continued
2.6. The Repository's Filesystem
2.7. The Repository
4.1. Branches of Development
4.2. Starting Repository Layout
4.3. Repository With New Copy
4.4. The Branching of One File's History
5.1. One Suggested Repository Layout.
5.2. Another Suggested Repository Layout.
7.1. Subversion's "Big Picture"
7.2. Files and Directories in Two Dimensions
7.3. Revisioning Time—the Third Dimension!

List of Tables

2.1. Repository Access URLs
7.1. A Brief Inventory of the Subversion Libraries
E.1. GUI Clients for Subversion

List of Examples

5.1. Using svnshell to Navigate the Repository
5.2. txn-info.sh (Reporting Outstanding Transactions)
5.3. Using Incremental Repository Dumps
6.1. Sample Registration Entries (.REG) File.
7.1. Using the Repository Layer
7.2. Using the Repository Layer with Python
7.3. A Simple Script to Check Out a Working Copy.
7.4. Contents of a Typical .svn/entries File
7.5. Effective Pool Usage