Part I. Getting to Know Subversion

Table of Contents

1. Fundamental Concepts
Version Control Basics
The Repository
The Working Copy
Versioning Models
The problem of file sharing
The lock-modify-unlock solution
The copy-modify-merge solution
Version Control the Subversion Way
Subversion Repositories
Revisions
Addressing the Repository
Subversion Working Copies
How the working copy works
Fundamental working copy interactions
Mixed-revision working copies
Summary
2. Basic Usage
Help!
Getting Data into Your Repository
Importing Files and Directories
Recommended Repository Layout
What's In a Name?
Creating a Working Copy
Basic Work Cycle
Update Your Working Copy
Make Your Changes
Review Your Changes
See an overview of your changes
Examine the details of your local modifications
Fix Your Mistakes
Resolve Any Conflicts
Viewing conflict differences interactively
Resolving conflict differences interactively
Postponing conflict resolution
Manual conflict resolution
Discarding your changes in favor of a newly fetched revision
Punting: using svn revert
Commit Your Changes
Examining History
Examining the Details of Historical Changes
Examining local changes
Comparing working copy to repository
Comparing repository revisions
Generating a List of Historical Changes
Browsing the Repository
Displaying file contents
Displaying line-by-line change attribution
Listing versioned directories
Fetching Older Repository Snapshots
Sometimes You Just Need to Clean Up
Disposing of a Working Copy
Recovering from an Interruption
Dealing with Structural Conflicts
An Example Tree Conflict
Summary
3. Advanced Topics
Revision Specifiers
Revision Keywords
Revision Dates
Peg and Operative Revisions
Properties
Why Properties?
Manipulating Properties
Properties and the Subversion Workflow
Inherited Properties
Automatic Property Setting
Subversion's Reserved Properties
Versioned properties
Unversioned properties
File Portability
File Content Type
File Executability
End-of-Line Character Sequences
Ignoring Unversioned Items
Keyword Substitution
Sparse Directories
Locking
Creating Locks
Discovering Locks
Breaking and Stealing Locks
Lock Communication
Externals Definitions
Changelists
Creating and Modifying Changelists
Changelists As Operation Filters
Changelist Limitations
Network Model
Requests and Responses
Client Credentials
Caching credentials
Disabling password caching
Removing cached credentials
Command-line authentication
Authentication wrap-up
Working Without a Working Copy
Remote command-line client operations
Using svnmucc
Summary
4. Branching and Merging
What's a Branch?
Using Branches
Creating a Branch
Working with Your Branch
The Key Concepts Behind Branching
Basic Merging
Changesets
Keeping a Branch in Sync
Subtree Merges and Subtree Mergeinfo
Reintegrating a Branch
Mergeinfo and Previews
Undoing Changes
Resurrecting Deleted Items
Advanced Merging
Cherrypicking
Merge Syntax: Full Disclosure
Merges Without Mergeinfo
More on Merge Conflicts
Blocking Changes
Merge-Sensitive Logs and Annotations
Noticing or Ignoring Ancestry
Merges and Moves
Preventing Naïve Clients from Committing Merges
The Final Word on Merge Tracking
Traversing Branches
Tags
Creating a Simple Tag
Creating a Complex Tag
Branch Maintenance
Repository Layout
Data Lifetimes
Common Branching Patterns
Release Branches
Feature Branches
Vendor Branches
General Vendor Branch Management Procedure
Vendor Branches from Foreign Repositories
Vendor Branches from Mirrored Sources
To Branch or Not to Branch?
Summary
5. Repository Administration
The Subversion Repository, Defined
Strategies for Repository Deployment
Planning Your Repository Organization
Deciding Where and How to Host Your Repository
Controlling Access to Your Repository
Creating and Configuring Your Repository
Creating the Repository
Implementing Repository Hooks
Hook script environment configuration
Common uses for hook scripts
Finding hook scripts or rolling your own
FSFS Configuration
Repository Maintenance
An Administrator's Toolkit
svnadmin
svnlook
svndumpfilter
svnrdump
svnsync
fsfs-reshard.py
Commit Log Message Correction
Managing Disk Space
How Subversion saves disk space
Removing dead transactions
Packing FSFS filesystems
Migrating Repository Data Elsewhere
Repository data migration using svnadmin
Repository data migration using svnrdump
Filtering Repository History
Repository Replication
Replication with svnsync
Partial replication with svnsync
A quick trick for mirror creation
Replication wrap-up
Repository Backup
Managing Repository UUIDs
Moving and Removing Repositories
Summary
6. Server Configuration
Overview
Choosing a Server Configuration
The svnserve Server
svnserve over SSH
The Apache HTTP Server
Recommendations
svnserve, a Custom Server
Invoking the Server
svnserve as daemon
svnserve via inetd
svnserve via xinetd
svnserve over a tunnel
svnserve as a Windows service
svnserve as a launchd job
Built-in Authentication and Authorization
Create a users file and realm
Set access controls
Using svnserve with SASL
Authenticating with SASL
SASL encryption
Tunneling over SSH
SSH Configuration Tricks
Initial setup
Controlling the invoked command
svnserve Configuration Reference
General configuration
Cyrus SASL configuration
httpd, the Apache HTTP Server
Prerequisites
Basic Apache Configuration
Authentication Options
Basic authentication
Digest authentication
Authorization Options
Blanket access control
Per-directory access control
Disabling path-based checks
Versioned in repository access files
Protecting network traffic with SSL
Subversion server SSL certificate configuration
Subversion client SSL certificate management
Tuning for Performance
KeepAlive
Bulk updates
Extra Goodies
Repository browsing
Apache logging
Write-through proxying
Other Apache features
Subversion Apache HTTP Server Configuration Reference
mod_dav_svn configuration directives
mod_authz_svn configuration directives
Path-Based Authorization
Getting Started with Path-Based Access Control
Access Control Groups
Username Aliases
Advanced Access Control Features
Some Gotchas with Access Control
High-level Logging
Server Optimization
Data Caching
Network Compression of Data
Supporting Multiple Repository Access Methods
7. Customizing Your Subversion Experience
Runtime Configuration Area
Configuration Area Layout
Configuration and the Windows Registry
Runtime Configuration Options
General configuration
Per-server configuration
Localization
Understanding Locales
Subversion's Use of Locales
Using External Editors
Using External Differencing and Merge Tools
External diff
External diff3
External merge
Summary
8. Embedding Subversion
Layered Library Design
Repository Layer
Repository Access Layer
Client Layer
Using the APIs
The Apache Portable Runtime Library
Functions and Batons
URL and Path Requirements
Using Languages Other Than C and C++
Code Samples
Summary