This text is a work in progress—highly subject to change—and may not accurately describe any released version of the Apache™ Subversion® software. Bookmarking or otherwise referring others to this page is probably not such a smart idea. Please visit for stable versions of this book.

Version Control with Subversion [DRAFT]

For Subversion 1.8

(Compiled from r6065)

Ben Collins-Sussman

Brian W. Fitzpatrick

C. Michael Pilato

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

Table of Contents

What Is Subversion?
Is Subversion the Right Tool?
Subversion's History
Subversion's Architecture
Subversion's Components
What's New in Subversion
How to Read This Book
Organization of This Book
This Book Is Free
I. Getting to Know Subversion
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
Addressing the Repository
Subversion Working Copies
How the working copy works
Fundamental working copy interactions
Mixed-revision working copies
2. Basic Usage
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
3. Advanced Topics
Revision Specifiers
Revision Keywords
Revision Dates
Peg and Operative Revisions
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
Creating Locks
Discovering Locks
Breaking and Stealing Locks
Lock Communication
Externals Definitions
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
4. Branching and Merging
What's a Branch?
Using Branches
Creating a Branch
Working with Your Branch
The Key Concepts Behind Branching
Basic Merging
Keeping a Branch in Sync
Subtree Merges and Subtree Mergeinfo
Reintegrating a Branch
Mergeinfo and Previews
Undoing Changes
Resurrecting Deleted Items
Advanced Merging
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
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?
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
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
6. Server Configuration
Choosing a Server Configuration
The svnserve Server
svnserve over SSH
The Apache HTTP Server
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
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
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
Understanding Locales
Subversion's Use of Locales
Using External Editors
Using External Differencing and Merge Tools
External diff
External diff3
External merge
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
II. Subversion Command Reference
I. svn Reference—Subversion Command-Line Client
svn add
svn blame (praise, annotate, ann)
svn cat
svn changelist (cl)
svn checkout (co)
svn cleanup
svn commit (ci)
svn copy (cp)
svn delete (del, remove, rm)
svn diff (di)
svn export
svn help (h, ?)
svn import
svn info
svn list (ls)
svn lock
svn log
svn merge
svn mergeinfo
svn mkdir
svn move (mv)
svn patch
svn propdel (pdel, pd)
svn propedit (pedit, pe)
svn propget (pget, pg)
svn proplist (plist, pl)
svn propset (pset, ps)
svn relocate
svn resolve
svn resolved
svn revert
svn status (stat, st)
svn switch (sw)
svn unlock
svn update (up)
svn upgrade
II. svnadmin Reference—Subversion Repository Administration
svnadmin crashtest
svnadmin create
svnadmin deltify
svnadmin dump
svnadmin freeze
svnadmin help (h, ?)
svnadmin hotcopy
svnadmin list-dblogs
svnadmin list-unused-dblogs
svnadmin load
svnadmin lock
svnadmin lslocks
svnadmin lstxns
svnadmin pack
svnadmin recover
svnadmin rmlocks
svnadmin rmtxns
svnadmin setlog
svnadmin setrevprop
svnadmin setuuid
svnadmin unlock
svnadmin upgrade
svnadmin verify
III. svnlook Reference—Subversion Repository Examination
svnlook author
svnlook cat
svnlook changed
svnlook date
svnlook diff
svnlook dirs-changed
svnlook filesize
svnlook help (h, ?)
svnlook history
svnlook info
svnlook lock
svnlook log
svnlook propget (pget, pg)
svnlook proplist (plist, pl)
svnlook tree
svnlook uuid
svnlook youngest
IV. svnserve Reference—Custom Subversion Server
V. svnversion Reference—Subversion Working Copy Version Info
VI. svnsync Reference—Subversion Repository Mirroring
svnsync copy-revprops
svnsync help
svnsync info
svnsync initialize (init)
svnsync synchronize (sync)
VII. svnrdump Reference—Remote Subversion Repository Data Migration
svnrdump dump
svnrdump help
svnrdump load
VIII. svndumpfilter Reference—Subversion History Filtering
svndumpfilter exclude
svndumpfilter include
svndumpfilter help
IX. svnmucc Reference—Subversion Multiple URL Command Client
X. Subversion Repository Hook Reference
III. Appendices
A. Subversion Quick-Start Guide
Installing Subversion
High-Speed Tutorial
B. Subversion for CVS Users
Revision Numbers Are Different Now
Directory Versions
More Disconnected Operations
Distinction Between Status and Update
Branches and Tags
Metadata Properties
Conflict Resolution
Binary Files and Translation
Versioned Modules
Converting a Repository from CVS to Subversion
C. WebDAV and Autoversioning
What Is WebDAV?
Client Interoperability
Standalone WebDAV Applications
Microsoft Office, Dreamweaver, Photoshop
cadaver, DAV Explorer
File-Explorer WebDAV Extensions
Microsoft Web Folders
Nautilus, Konqueror
WebDAV Filesystem Implementation
WebDrive, NetDrive
Mac OS X
Linux davfs2
D. The Berkeley DB Legacy Filesystem
Configuring Your Berkeley DB Environment
Limitations of Berkeley DB
Architectural Limitations
Network Share Deployment
Fault Tolerance and the Need for Recovery
Maintaining Berkeley DB Repositories
Berkeley DB Recovery
Purging unused Berkeley DB logfiles
Berkeley DB Utilities
E. Copyright

List of Figures

1. Subversion's architecture
1.1. A typical client/server system
1.2. The problem to avoid
1.3. The lock-modify-unlock solution
1.4. The copy-modify-merge solution
1.5. The copy-modify-merge solution (continued)
1.6. Tree changes over time
1.7. The repository's filesystem
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
8.1. Files and directories in two dimensions
8.2. Versioning time—the third dimension!

List of Tables

1.1. Repository access URLs
2.1. Common log requests
4.1. Branching and merging commands
6.1. Comparison of Subversion server options
C.1. Common WebDAV clients

List of Examples

4.1. Merge-tracking gatekeeper start-commit hook script
5.1. hooks-env (custom hook script environment configuration)
5.2. start-commit hook to require merge tracking support
5.3. (reporting outstanding transactions)
5.4. Mirror repository's pre-revprop-change hook script
5.5. Mirror repository's start-commit hook script
6.1. A sample svnserve launchd job definition
6.2. A sample configuration for anonymous access
6.3. A sample configuration for authenticated access
6.4. A sample configuration for mixed authenticated/anonymous access
6.5. Disabling path checks altogether
6.6. Using single versioned in repo access file
6.7. Using per repository in repo access files
7.1. Sample registration entries (.reg) file
7.3. diffwrap.bat
7.5. diff3wrap.bat
7.7. mergewrap.bat
8.1. Using the repository layer
8.2. Using the repository layer with Python
8.3. A Python status crawler