- •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
Server Configuration
command="svnserve -t --tunnel-user=sally" TYPE2 KEY2 sally@example.com
This example allows both Harry and Sally to connect to the same account via public-key authentication. Each of them has a custom command that will be executed; the --tunnel-user option tells svnserve -t to assume that the named argument is the authenticated user. Without --tunnel-user, it would appear as though all commits were coming from the one shared system account.
A final word of caution: giving a user access to the server via public-key in a shared account might still allow other forms of SSH access, even if you've set the the command value in authorized_keys. For example, the user may still get shell access through SSH, or be able to perform X11 or general port-forwarding through your server. To give the user as little permission as possible, you may want to specify a number of restrictive options immediately after the command:
command="svnserve -t --tunnel-user=harry",no-port-forwarding,\ no-agent-forwarding,no-X11-forwarding,no-pty \
TYPE1 KEY1 harry@example.com
httpd, the Apache HTTP server
The Apache HTTP Server is a “heavy duty” network server that Subversion can leverage. Via a custom module, httpd makes Subversion repositories available to clients via the WebDAV/DeltaV protocol, which is an extension to HTTP 1.1 (see http://www.webdav.org/ for more information.) This protocol takes the ubiquitous HTTP protocol that is the core of the World Wide Web, and adds writing—specifically, versioned writing—capabilities. The result is a standardized, robust system that is conveniently packaged as part of the Apache 2.0 software, is supported by numerous operating systems and third-party products, and doesn't require network administrators to open up yet another custom port. 22 While an Apache-Subversion server has more features than svnserve, it's also a bit more difficult to set up. With flexibility often comes more complexity.
Much of the following discussion includes references to Apache configuration directives. While some examples are given of the use of these directives, describing them in full is outside the scope of this chapter. The Apache team maintains excellent documentation, publicly available on their website at http://httpd.apache.org. For example, a general reference for the configuration directives is located at http://httpd.apache.org/docs-2.0/mod/directives.html.
Also, as you make changes to your Apache setup, it is likely that somewhere along the way a mistake will be made. If you are not already familiar with Apache's logging subsystem, you should become aware of it. In your httpd.conf file are directives that specify the on-disk locations of the access and error logs generated by Apache (the CustomLog and ErrorLog directives, respectively). Subversion's mod_dav_svn uses Apache's error logging interface as well. You can always browse the contents of those files for information that might reveal the source of a problem that is not clearly noticeable otherwise.
Why Apache 2?
If you're a system administrator, it's very likely that you're already running the Apache web server and have some prior experience with it. At the time of writing, Apache 1.3 is by far the most popular version of Apache. The world has been somewhat slow to upgrade to the Apache 2.X series for various reasons: some people fear change, especially changing something as critical as a web server. Other people depend on plug-in modules that only work against the Apache 1.3 API, and are waiting for a 2.X port. Whatever the reason, many people begin to worry when they first discover that Subversion's Apache module is written specifically for the Apache 2 API.
The proper response to this problem is: don't worry about it. It's easy to run Apache 1.3 and Apache 2 side-by-side; simply install them to separate places, and use Apache 2 as a dedicated Subversion server that runs on a port other than 80. Clients can access the repository by placing the port number into the URL:
22They really hate doing that.
102
Server Configuration
$ svn checkout http://host.example.com:7382/repos/project
…
Prerequisites
To network your repository over HTTP, you basically need four components, available in two packages. You'll need Apache httpd 2.0, the mod_dav DAV module that comes with it, Subversion, and the mod_dav_svn filesystem provider module distributed with Subversion. Once you have all of those components, the process of networking your repository is as simple as:
•getting httpd 2.0 up and running with the mod_dav module,
•installing the mod_dav_svn plugin to mod_dav, which uses Subversion's libraries to access the repository, and
•configuring your httpd.conf file to export (or expose) the repository.
You can accomplish the first two items either by compiling httpd and Subversion from source code, or by installing pre-built binary packages of them on your system. For the most up-to-date information on how to compile Subversion for use with the Apache HTTP Server, as well as how to compile and configure Apache itself for this purpose, see the INSTALL file in the top level of the Subversion source code tree.
Basic Apache Configuration
Once you have all the necessary components installed on your system, all that remains is the configuration of Apache via its httpd.conf file. Instruct Apache to load the mod_dav_svn module using the LoadModule directive. This directive must precede any other Subversion-related configuration items. If your Apache was installed using the default layout, your mod_dav_svn module should have been installed in the modules subdirectory of the Apache install location (often /usr/local/apache2). The LoadModule directive has a simple syntax, mapping a named module to the location of a shared library on disk:
LoadModule dav_svn_module |
modules/mod_dav_svn.so |
Note that if mod_dav was compiled as a shared object (instead of statically linked directly to the httpd binary), you'll need a similar LoadModule statement for it, too. Be sure that it comes before the mod_dav_svn line:
LoadModule |
dav_module |
modules/mod_dav.so |
LoadModule |
dav_svn_module |
modules/mod_dav_svn.so |
At a later location in your configuration file, you now need to tell Apache where you keep your Subversion repository (or repositories). The Location directive has an XML-like notation, starting with an opening tag, and ending with a closing tag, with various other configuration directives in the middle. The purpose of the Location directive is to instruct Apache to do something special when handling requests that are directed at a given URL or one of its children. In the case of Subversion, you want Apache to simply hand off support for URLs that point at versioned resources to the DAV layer. You can instruct Apache to delegate the handling of all URLs whose path portions (the part of the URL that follows the server's name and the optional port number) begin with /repos/ to a DAV provider whose repository is located at /absolute/path/to/repository using the following httpd.conf syntax:
103
Server Configuration
<Location /repos> DAV svn
SVNPath /absolute/path/to/repository </Location>
If you plan to support multiple Subversion repositories that will reside in the same parent directory on your local disk, you can use an alternative directive, the SVNParentPath directive, to indicate that common parent directory. For example, if you know you will be creating multiple Subversion repositories in a directory / usr/local/svn that would be accessed via URLs like http://my.server.com/svn/repos1, http://my.server.com/svn/repos2, and so on, you could use the httpd.conf configuration syntax in the following example:
<Location /svn> DAV svn
# any "/svn/foo" URL will map to a repository /usr/local/svn/foo SVNParentPath /usr/local/svn
</Location>
Using the previous syntax, Apache will delegate the handling of all URLs whose path portions begin with /svn/ to the Subversion DAV provider, which will then assume that any items in the directory specified by the SVNParentPath directive are actually Subversion repositories. This is a particularly convenient syntax in that, unlike the use of the SVNPath directive, you don't have to restart Apache in order to create and network new repositories.
Be sure that when you define your new Location, it doesn't overlap with other exported Locations. For example, if your main DocumentRoot is /www, do not export a Subversion repository in <Location /www/repos>. If a request comes in for the URI /www/repos/foo.c, Apache won't know whether to look for a file repos/ foo.c in the DocumentRoot, or whether to delegate mod_dav_svn to return foo.c from the Subversion repository.
Server Names and the COPY Request
Subversion makes use of the COPY request type to perform server-side copies of files and directories. As part of the sanity checking done by the Apache modules, the source of the copy is expected to be located on the same machine as the destination of the copy. To satisfy this requirement, you might need to tell mod_dav the name you use as the hostname of your server. Generally, you can use the ServerName directive in httpd.conf to accomplish this.
ServerName svn.example.com
If you are using Apache's virtual hosting support via the NameVirtualHost directive, you may need to use the ServerAlias directive to specify additional names that your server is known by. Again, refer to the Apache documentation for full details.
At this stage, you should strongly consider the question of permissions. If you've been running Apache for some time now as your regular web server, you probably already have a collection of content—web pages, scripts and such. These items have already been configured with a set of permissions that allows them to work with Apache, or more appropriately, that allows Apache to work with those files. Apache, when used as a Subversion server, will also need the correct permissions to read and write to your Subversion repository. (See Servers and Permissions: A Word of Warning.)
You will need to determine a permission system setup that satisfies Subversion's requirements without messing up any previously existing web page or script installations. This might mean changing the permissions on your Subver-
104