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