- •Table of Contents
- •Foreword
- •Preface
- •Audience
- •How to Read this Book
- •Conventions Used in This Book
- •Typographic Conventions
- •Icons
- •Organization of This Book
- •New in Subversion 1.1
- •This Book is Free
- •Acknowledgments
- •From Ben Collins-Sussman
- •From Brian W. Fitzpatrick
- •From C. Michael Pilato
- •Chapter 1. Introduction
- •What is Subversion?
- •Subversion's History
- •Subversion's Features
- •Subversion's Architecture
- •Installing Subversion
- •Subversion's Components
- •A Quick Start
- •Chapter 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
- •Chapter 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 diff
- •Examining Local Changes
- •Comparing Working Copy to Repository
- •Comparing Repository to Repository
- •svn list
- •A Final Word on History
- •Other Useful Commands
- •svn cleanup
- •svn import
- •Summary
- •Chapter 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
- •The Key Concept Behind Merging
- •Best Practices for Merging
- •Tracking Merges Manually
- •Previewing Merges
- •Merge Conflicts
- •Noticing or Ignoring Ancestry
- •Common Use-Cases
- •Merging a Whole Branch to Another
- •Undoing Changes
- •Resurrecting Deleted Items
- •Common Branching Patterns
- •Release Branches
- •Feature Branches
- •Switching a Working Copy
- •Tags
- •Creating a Simple Tag
- •Creating a Complex Tag
- •Branch Maintenance
- •Repository Layout
- •Data Lifetimes
- •Summary
- •Chapter 5. Repository Administration
- •Repository Basics
- •Understanding Transactions and Revisions
- •Unversioned Properties
- •Repository Data-Stores
- •Berkeley DB
- •FSFS
- •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
- •Chapter 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
- •SSH configuration tricks
- •Initial setup
- •Controlling the invoked command
- •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
- •Disabling Path-based Checks
- •Extra Goodies
- •Repository Browsing
- •Other Features
- •Supporting Multiple Repository Access Methods
- •Chapter 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
- •svn:special
- •Automatic Property Setting
- •Peg and Operative Revisions
- •Externals Definitions
- •Vendor branches
- •General Vendor Branch Management Procedure
- •svn_load_dirs.pl
- •Localization
- •Understanding locales
- •Subversion's use of locales
- •Subversion Repository URLs
- •Chapter 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
- •Chapter 9. Subversion Complete Reference
- •The Subversion Command Line Client: svn
- •svn Switches
- •svn Subcommands
- •svn blame
- •svn checkout
- •svn cleanup
- •svn commit
- •svn copy
- •svn delete
- •svn diff
- •svn export
- •svn help
- •svn list
- •svn merge
- •svn mkdir
- •svn move
- •svn propedit
- •svn proplist
- •svn resolved
- •svn revert
- •svn status
- •svn switch
- •svn update
- •svnadmin
- •svnadmin Switches
- •svnadmin Subcommands
- •svnadmin create
- •svnadmin deltify
- •svnadmin dump
- •svnadmin help
- •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 changed
- •svnlook date
- •svnlook help
- •svnlook history
- •svnlook tree
- •svnlook uuid
- •svnserve
- •svnserve Switches
- •svnversion
- •svnversion
- •mod_dav_svn Configuration Directives
- •Appendix 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
- •Appendix 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?
- •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.
- •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.
- •Appendix 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
- •Unix: Nautilus 2
- •Linux davfs2
- •Appendix D. Third Party Tools
- •Clients and Plugins
- •Language Bindings
- •Repository Converters
- •Higher Level Tools
- •Repository Browsing Tools
- •Appendix E. Copyright
Chapter 5. Repository Administration
The Subversion repository is the central storehouse of versioned data for any number of projects. As such, it becomes an obvious candidate for all the love and attention an administrator can offer. While the repository is generally a low-maintenance item, it is important to understand how to properly configure and care for it so that potential problems are avoided, and actual problems are safely resolved.
In this chapter, we'll discuss how to create and configure a Subversion repository. We'll also talk about repository maintenance, including the use of the svnlook and svnadmin tools (which are provided with Subversion). We'll address some common questions and mistakes, and give some suggestions on how to arrange the data in the repository.
If you plan to access a Subversion repository only in the role of a user whose data is under version control (that is, via a Subversion client), you can skip this chapter altogether. However, if you are, or wish to become, a Subversion repository administrator, 12 you should definitely pay attention to this chapter.
Repository Basics
Before jumping into the broader topic of repository administration, let's further define what a repository is. How does it look? How does it feel? Does it take its tea hot or iced, sweetened, and with lemon? As an administrator, you'll be expected to understand the composition of a repository both from a logical perspective—dealing with how data is represented inside the repository—and from a physical nuts-and-bolts perspective—how a repository looks and acts with respect to non-Subversion tools. The following section covers some of these basic concepts at a very high level.
Understanding Transactions and Revisions
Conceptually speaking, a Subversion repository is a sequence of directory trees. Each tree is a snapshot of how the files and directories versioned in your repository looked at some point in time. These snapshots are created as a result of client operations, and are called revisions.
Every revision begins life as a transaction tree. When doing a commit, a client builds a Subversion transaction that mirrors their local changes (plus any additional changes that might have been made to the repository since the beginning of the client's commit process), and then instructs the repository to store that tree as the next snapshot in the sequence. If the commit succeeds, the transaction is effectively promoted into a new revision tree, and is assigned a new revision number. If the commit fails for some reason, the transaction is destroyed and the client is informed of the failure.
Updates work in a similar way. The client builds a temporary transaction tree that mirrors the state of the working copy. The repository then compares that transaction tree with the revision tree at the requested revision (usually the most recent, or “youngest” tree), and sends back information that informs the client about what changes are needed to transform their working copy into a replica of that revision tree. After the update completes, the temporary transaction is deleted.
The use of transaction trees is the only way to make permanent changes to a repository's versioned filesystem. However, it's important to understand that the lifetime of a transaction is completely flexible. In the case of updates, transactions are temporary trees that are immediately destroyed. In the case of commits, transactions are transformed into permanent revisions (or removed if the commit fails). In the case of an error or bug, it's possible that a transaction can be accidentally left lying around in the repository (not really affecting anything, but still taking up space).
In theory, someday whole workflow applications might revolve around more fine-grained control of transaction lifetime. It is feasible to imagine a system whereby each transaction slated to become a revision is left in stasis well after the client finishes describing its changes to repository. This would enable each new commit to be reviewed by
12This may sound really prestigious and lofty, but we're just talking about anyone who is interested in that mysterious realm beyond the working copy where everyone's data hangs out.
65