This documentation was written to describe the 1.6.x series of Subversion. If you are running a different version of Subversion, you are strongly encouraged to visit http://www.svnbook.com/ and instead consult the version of this documentation appropriate for your version of Subversion.

Version Control with Subversion
     Next

Version Control with Subversion

For Subversion 1.6

(Compiled from r6066)

Ben Collins-Sussman

Brian W. Fitzpatrick

C. Michael Pilato

Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 http://creativecommons.org/licenses/by/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

(TBA)

Table of Contents

Foreword
Preface
What Is Subversion?
Is Subversion the Right Tool?
Subversion's History
Subversion's Architecture
Subversion's Components
What's New in Subversion
Audience
How to Read This Book
Organization of This Book
This Book Is Free
Acknowledgments
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
Merging conflicts by hand
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
svn cat
svn list
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
Automatic Property Setting
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
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
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
Keeping a Reintegrated Branch Alive
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
svn_load_dirs.pl
Summary
5. Repository Administration
The Subversion Repository, Defined
Strategies for Repository Deployment
Planning Your Repository Organization
Deciding Where and How to Host Your Repository
Choosing a Data Store
Berkeley DB
FSFS
Creating and Configuring Your Repository
Creating the Repository
Implementing Repository Hooks
Berkeley DB Configuration
FSFS Configuration
Repository Maintenance
An Administrator's Toolkit
svnadmin
svnlook
svndumpfilter
svnsync
fsfs-reshard.py
Berkeley DB utilities
Commit Log Message Correction
Managing Disk Space
How Subversion saves disk space
Removing dead transactions
Purging unused Berkeley DB logfiles
Packing FSFS filesystems
Berkeley DB Recovery
Migrating Repository Data Elsewhere
Filtering Repository History
Repository Replication
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 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
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
Protecting network traffic with SSL
Subversion server SSL certificate configuration
Subversion client SSL certificate management
Extra Goodies
Repository browsing
Apache logging
Write-through proxying
Other Apache features
Path-Based Authorization
High-level Logging
Supporting Multiple Repository Access Methods
7. Customizing Your Subversion Experience
Runtime Configuration Area
Configuration Area Layout
Configuration and the Windows Registry
Configuration Options
Servers
Config
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
Inside the Working Copy Administration Area
The Entries File
Pristine Copies and Property Files
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
9. Subversion Complete Reference
svn—Subversion Command-Line Client
svn Options
svn Subcommands
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 propdel (pdel, pd)
svn propedit (pedit, pe)
svn propget (pget, pg)
svn proplist (plist, pl)
svn propset (pset, ps)
svn resolve
svn resolved
svn revert
svn status (stat, st)
svn switch (sw)
svn unlock
svn update (up)
svnadmin—Subversion Repository Administration
svnadmin Options
svnadmin Subcommands
svnadmin crashtest
svnadmin create
svnadmin deltify
svnadmin dump
svnadmin help (h, ?)
svnadmin hotcopy
svnadmin list-dblogs
svnadmin list-unused-dblogs
svnadmin load
svnadmin lslocks
svnadmin lstxns
svnadmin pack
svnadmin recover
svnadmin rmlocks
svnadmin rmtxns
svnadmin setlog
svnadmin setrevprop
svnadmin setuuid
svnadmin upgrade
svnadmin verify
svnlook—Subversion Repository Examination
svnlook Options
svnlook Subcommands
svnlook author
svnlook cat
svnlook changed
svnlook date
svnlook diff
svnlook dirs-changed
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
svnsync—Subversion Repository Mirroring
svnsync Options
svnsync Subcommands
svnsync copy-revprops
svnsync help
svnsync info
svnsync initialize (init)
svnsync synchronize (sync)
svnserve—Custom Subversion Server
svnserve Options
svndumpfilter—Subversion History Filtering
svndumpfilter Options
svndumpfilter Subcommands
svndumpfilter exclude
svndumpfilter include
svndumpfilter help
svnversion—Subversion Working Copy Version Info
svnversion
mod_dav_svn—Subversion Apache HTTP Server Module
mod_dav_svn Configuration Directives
mod_authz_svn—Subversion Apache HTTP Authorization Module
mod_authz_svn Configuration Directives
Subversion Properties
Versioned Properties
Unversioned Properties
Repository Hooks
start-commit
pre-commit
post-commit
pre-revprop-change
post-revprop-change
pre-lock
post-lock
pre-unlock
post-unlock
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
Status
Update
Branches and Tags
Metadata Properties
Conflict Resolution
Binary Files and Translation
Versioned Modules
Authentication
Converting a Repository from CVS to Subversion
C. WebDAV and Autoversioning
What Is WebDAV?
Autoversioning
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. Copyright
Index

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
5.1. Repository data store comparison
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. txn-info.sh (reporting outstanding transactions)
5.2. Mirror repository's pre-revprop-change hook script
5.3. 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
7.1. Sample registration entries (.reg) file
7.2. diffwrap.py
7.3. diffwrap.bat
7.4. diff3wrap.py
7.5. diff3wrap.bat
7.6. mergewrap.py
7.7. mergewrap.bat
8.1. Using the repository layer
8.2. Using the repository layer with Python
8.3. A Python status crawler
     Next
     Foreword