Version Control with Subversion [DRAFT]

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

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

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

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

svnserve

V. svnversion Reference—Subversion Working Copy Version Info

svnversion

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

svnmucc

X. Subversion Repository Hook Reference

start-commit

pre-commit

post-commit

pre-revprop-change

post-revprop-change

pre-lock

post-lock

pre-unlock

post-unlock

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

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. 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

Index