Version Control with Subversion
   Next

Version Control with Subversion

Draft Revision 9837

Ben Collins-Sussman

Brian W. Fitzpatrick

C. Michael Pilato

Copyright © 2002, 2003, 2004 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/1.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

(TBA)

Table of Contents

Foreword
Preface
Audience
How to Read this Book
Conventions Used in This Book
Typographic Conventions
Icons
Organization of This Book
This Book is Free
Acknowledgments
From Ben Collins-Sussman
From Brian W. Fitzpatrick
From C. Michael Pilato
1. Introduction
What is Subversion?
Subversion's History
Subversion's Features
Subversion's Architecture
Installing Subversion
Subversion's Components
A Quick Start
2. Basic Concepts
The Repository
Versioning Models
The Problem of File-Sharing
The Lock-Modify-Unlock Solution
The Copy-Modify-Merge Solution
Subversion in Action
Working Copies
Revisions
How Working Copies Track the Repository
The Limitations of Mixed Revisions
Summary
3. Guided Tour
Help!
Import
Revisions: Numbers, Keywords, and Dates, Oh My!
Revision Numbers
Revision Keywords
Revision Dates
Initial Checkout
Basic Work Cycle
Update Your Working Copy
Make Changes to Your Working Copy
Examine Your Changes
svn status
svn diff
svn revert
Resolve Conflicts (Merging Others' Changes)
Merging Conflicts by Hand
Copying a File Onto Your Working File
Punting: Using svn revert
Commit Your Changes
Examining History
svn log
svn diff
Examining Local Changes
Comparing Working Copy to Repository
Comparing Repository to Repository
svn cat
svn list
A Final Word on History
Other Useful Commands
svn cleanup
svn import
Summary
4. Branching and Merging
What's a Branch?
Using Branches
Creating a Branch
Working with Your Branch
The Key Concepts Behind Branches
Copying Changes Between Branches
Copying Specific Changes
Best Practices for Merging
Tracking Merges Manually
Previewing Merges
Noticing or Ignoring Ancestry
Common Use-Cases for Merging
Merging a Whole Branch to Another
Undoing Changes
Resurrecting Deleted Items
Switching a Working Copy
Tags
Creating a Simple Tag
Creating a Complex Tag
Branch Maintenance
Repository Layout
Data Lifetimes
Summary
5. Repository Administration
Repository Basics
Understanding Transactions and Revisions
Unversioned Properties
Berkeley DB
Repository Creation and Configuration
Hook Scripts
Berkeley DB Configuration
Repository Maintenance
An Administrator's Toolkit
svnlook
svnadmin
svndumpfilter
svnshell.py
Berkeley DB Utilities
Repository Cleanup
Managing Disk Space
Repository Recovery
Migrating a Repository
Repository Backup
Adding Projects
Choosing a Repository Layout
Creating the Layout, and Importing Initial Data
Summary
6. Server Configuration
Overview
Network Model
Requests and Responses
Client Credentials Caching
svnserve, a custom server
Invoking the Server
Built-in authentication and authorization
Create a 'users' file and realm
Set access controls
SSH authentication and authorization
httpd, the Apache HTTP server
Prerequisites
Basic Apache Configuration
Authentication Options
Basic HTTP Authentication
SSL Certificate Management
Authorization Options
Blanket Access Control
Per-Directory Access Control
Extra Goodies
Repository Browsing
Other Features
Supporting Multiple Repository Access Methods
7. Advanced Topics
Runtime Configuration Area
Configuration Area Layout
Configuration and the Windows Registry
Configuration Options
Servers
Config
Properties
Why Properties?
Manipulating Properties
Special Properties
svn:executable
svn:mime-type
svn:ignore
svn:keywords
svn:eol-style
svn:externals
Automatic Property Setting
Externals Definitions
Vendor branches
General Vendor Branch Management Procedure
svn_load_dirs.pl
8. Developer Information
Layered Library Design
Repository Layer
Repository Access Layer
RA-DAV (Repository Access Using HTTP/DAV)
RA-SVN (Custom Protocol Repository Access)
RA-Local (Direct Repository Access)
Your RA Library Here
Client Layer
Using the APIs
The Apache Portable Runtime Library
URL and Path Requirements
Using Languages Other than C and C++
Inside the Working Copy Administration Area
The Entries File
Pristine Copies and Property Files
WebDAV
Programming with Memory Pools
Contributing to Subversion
Join the Community
Get the Source Code
Become Familiar with Community Policies
Make and Test Your Changes
Donate Your Changes
9. Subversion Complete Reference
The Subversion Command Line Client: svn
svn Switches
svn Subcommands
svn add
svn blame
svn cat
svn checkout
svn cleanup
svn commit
svn copy
svn delete
svn diff
svn export
svn help
svn import
svn info
svn list
svn log
svn merge
svn mkdir
svn move
svn propdel
svn propedit
svn propget
svn proplist
svn propset
svn resolved
svn revert
svn status
svn switch
svn update
svnadmin
svnadmin Switches
svnadmin Subcommands
svnadmin create
svnadmin deltify
svnadmin dump
svnadmin help
svnadmin hotcopy
svnadmin list-dblogs
svnadmin list-unused-dblogs
svnadmin load
svnadmin lstxns
svnadmin recover
svnadmin rmtxns
svnadmin setlog
svnadmin verify
svnlook
svnlook Switches
svnlook
svnlook author
svnlook cat
svnlook changed
svnlook date
svnlook diff
svnlook dirs-changed
svnlook help
svnlook history
svnlook info
svnlook log
svnlook propget
svnlook proplist
svnlook tree
svnlook uuid
svnlook youngest
svnserve
svnserve Switches
A. 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
Authentication
Converting a Repository from CVS to Subversion
B. Troubleshooting
Common Problems
Problems Using Subversion
Every time I try to access my repository, my Subversion client just hangs.
Every time I try to run svn, it says my working copy is locked.
I'm getting errors finding or opening a repository, but I know my repository URL is correct.
How can I specify a Windows drive letter in a file:// URL?
I'm having trouble doing write operations to a Subversion repository over a network.
Under Windows XP, the Subversion server sometimes seems to send out corrupted data.
What is the best method of doing a network trace of the conversation between a Subversion client and Apache server?
I just built the distribution binary, and when I try to check out Subversion, I get an error about an "Unrecognized URL scheme."
Why does the 'svn revert' command require an explicit target? Why is it not recursive by default? This behavior differs from almost all the other subcommands.
When I start Apache, mod_dav_svn complains about a "bad database version", that it found db-3.X, rather than db-4.X.
I'm getting "Function not implemented" errors on RedHat 9, and nothing works. How do I fix this?
Why does log say "(no author)" for files committed or imported via Apache (ra_dav)?
I'm getting occasional "Access Denied" errors on Windows. They seem to happen at random.
On FreeBSD, certain operations (especially svnadmin create) sometimes hang.
I can see my repository in a web browser, but 'svn checkout' gives me an error about "301 Moved Permanently".
I'm trying to look at an old version of my file, but svn says something about "path not found".
C. WebDAV and Autoversioning
Basic WebDAV Concepts
Just Plain WebDAV
DeltaV Extensions
Subversion and DeltaV
Mapping Subversion to DeltaV
Autoversioning Support
The mod_dav_lock Alternative
Autoversioning Interoperability
Win32 WebFolders
Mac OS X
Unix: Nautilus 2
Linux davfs2
D. Third Party Tools
Clients and Plugins
Language Bindings
Repository Converters
Higher Level Tools
Repository Browsing Tools
E. Copyright

List of Figures

1.1. Subversion's Architecture
2.1. A typical client/server system
2.2. The problem to avoid
2.3. The lock-modify-unlock solution
2.4. The copy-modify-merge solution
2.5. The copy-modify-merge solution (continued)
2.6. The repository's filesystem
2.7. The repository
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. Revisioning time—the third dimension!

List of Tables

2.1. Repository Access URLs
6.1. Network Server Comparison
8.1. A Brief Inventory of the Subversion Libraries

List of Examples

5.1. Using svnshell to Navigate the Repository
5.2. txn-info.sh (Reporting Outstanding Transactions)
6.1. A sample configuration for anonymous access.
6.2. A sample configuration for authenticated access.
6.3. A sample configuration for mixed authenticated/anonymous access.
7.1. Sample Registration Entries (.reg) File.
8.1. Using the Repository Layer
8.2. Using the Repository Layer with Python
8.3. A Simple Script to Check Out a Working Copy.
8.4. Contents of a Typical .svn/entries File
8.5. Effective Pool Usage
   Next
   Foreword