- •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
Version Control with Subversion
For Subversion 1.1
(book compiled from Revision 1337)
Ben Collins-Sussman
Brian W. Fitzpatrick
C. Michael Pilato
Version Control with Subversion: For Subversion 1.1: (book compiled from Revision 1337)
by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato
Published (TBA)
Copyright © 2002, 2003, 2004, 2005 Ben Collins-SussmanBrian W. FitzpatrickC. 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/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
Table of Contents |
|
Foreword ...................................................................................................................................... |
11 |
Preface ......................................................................................................................................... |
13 |
Audience .............................................................................................................................. |
13 |
How to Read this Book ........................................................................................................... |
13 |
Conventions Used in This Book ................................................................................................ |
14 |
Typographic Conventions ................................................................................................ |
14 |
Icons ........................................................................................................................... |
14 |
Organization of This Book ....................................................................................................... |
15 |
New in Subversion 1.1 ............................................................................................................ |
16 |
This Book is Free ................................................................................................................... |
17 |
Acknowledgments .................................................................................................................. |
17 |
From Ben Collins-Sussman .............................................................................................. |
17 |
From Brian W. Fitzpatrick ............................................................................................... |
18 |
From C. Michael Pilato ................................................................................................... |
18 |
1. Introduction ............................................................................................................................... |
1 |
What is Subversion? ............................................................................................................... |
1 |
Subversion's History ............................................................................................................... |
1 |
Subversion's Features .............................................................................................................. |
2 |
Subversion's Architecture ........................................................................................................ |
3 |
Installing Subversion .............................................................................................................. |
4 |
Subversion's Components ........................................................................................................ |
5 |
A Quick Start ........................................................................................................................ |
5 |
2. Basic Concepts ........................................................................................................................... |
8 |
The Repository ...................................................................................................................... |
8 |
Versioning Models ................................................................................................................. |
8 |
The Problem of File-Sharing ............................................................................................ |
9 |
The Lock-Modify-Unlock Solution .................................................................................... |
9 |
The Copy-Modify-Merge Solution .................................................................................... |
11 |
Subversion in Action .............................................................................................................. |
12 |
Working Copies ............................................................................................................. |
13 |
Revisions ...................................................................................................................... |
15 |
How Working Copies Track the Repository ........................................................................ |
17 |
The Limitations of Mixed Revisions .................................................................................. |
18 |
Summary .............................................................................................................................. |
18 |
3. Guided Tour .............................................................................................................................. |
19 |
Help! ................................................................................................................................... |
19 |
Import .................................................................................................................................. |
19 |
Revisions: Numbers, Keywords, and Dates, Oh My! ..................................................................... |
19 |
Revision Numbers .......................................................................................................... |
19 |
Revision Keywords ........................................................................................................ |
19 |
Revision Dates .............................................................................................................. |
20 |
Initial Checkout ..................................................................................................................... |
22 |
Basic Work Cycle .................................................................................................................. |
23 |
Update Your Working Copy ............................................................................................. |
24 |
Make Changes to Your Working Copy ............................................................................... |
24 |
Examine Your Changes ................................................................................................... |
26 |
Resolve Conflicts (Merging Others' Changes) ...................................................................... |
31 |
Commit Your Changes .................................................................................................... |
34 |
Examining History ................................................................................................................. |
35 |
svn log ......................................................................................................................... |
35 |
svn diff ........................................................................................................................ |
37 |
svn cat ......................................................................................................................... |
38 |
svn list ......................................................................................................................... |
39 |
iv |
|
Version Control with Subversion |
|
A Final Word on History ................................................................................................. |
39 |
Other Useful Commands ......................................................................................................... |
39 |
svn cleanup ................................................................................................................... |
40 |
svn import .................................................................................................................... |
40 |
Summary .............................................................................................................................. |
40 |
4. Branching and Merging ............................................................................................................... |
42 |
What's a Branch? ................................................................................................................... |
42 |
Using Branches ..................................................................................................................... |
42 |
Creating a Branch .......................................................................................................... |
44 |
Working with Your Branch .............................................................................................. |
46 |
The Key Concepts Behind Branches .................................................................................. |
48 |
Copying Changes Between Branches ......................................................................................... |
48 |
Copying Specific Changes ............................................................................................... |
48 |
The Key Concept Behind Merging .................................................................................... |
51 |
Best Practices for Merging ............................................................................................... |
51 |
Common Use-Cases ............................................................................................................... |
54 |
Merging a Whole Branch to Another .................................................................................. |
54 |
Undoing Changes ........................................................................................................... |
56 |
Resurrecting Deleted Items .............................................................................................. |
57 |
Common Branching Patterns ............................................................................................ |
58 |
Switching a Working Copy ...................................................................................................... |
60 |
Tags .................................................................................................................................... |
61 |
Creating a Simple Tag ..................................................................................................... |
61 |
Creating a Complex Tag .................................................................................................. |
62 |
Branch Maintenance ............................................................................................................... |
63 |
Repository Layout .......................................................................................................... |
63 |
Data Lifetimes ............................................................................................................... |
63 |
Summary .............................................................................................................................. |
64 |
5. Repository Administration ............................................................................................................ |
65 |
Repository Basics ................................................................................................................... |
65 |
Understanding Transactions and Revisions .......................................................................... |
65 |
Unversioned Properties ................................................................................................... |
66 |
Repository Data-Stores ................................................................................................... |
66 |
Repository Creation and Configuration ....................................................................................... |
68 |
Hook Scripts ................................................................................................................. |
70 |
Berkeley DB Configuration .............................................................................................. |
72 |
Repository Maintenance .......................................................................................................... |
72 |
An Administrator's Toolkit ............................................................................................... |
72 |
Repository Cleanup ........................................................................................................ |
81 |
Managing Disk Space ..................................................................................................... |
83 |
Repository Recovery ...................................................................................................... |
84 |
Migrating a Repository .................................................................................................... |
85 |
Repository Backup ......................................................................................................... |
88 |
Adding Projects ..................................................................................................................... |
89 |
Choosing a Repository Layout .......................................................................................... |
90 |
Creating the Layout, and Importing Initial Data ................................................................... |
91 |
Summary .............................................................................................................................. |
92 |
6. Server Configuration ................................................................................................................... |
93 |
Overview .............................................................................................................................. |
93 |
Network Model ..................................................................................................................... |
94 |
Requests and Responses .................................................................................................. |
94 |
Client Credentials Caching ............................................................................................... |
94 |
svnserve, a custom server ........................................................................................................ |
96 |
Invoking the Server ........................................................................................................ |
96 |
Built-in authentication and authorization ............................................................................. |
97 |
SSH authentication and authorization ................................................................................. |
99 |
SSH configuration tricks .................................................................................................. |
101 |
httpd, the Apache HTTP server ................................................................................................. |
102 |
v
Version Control with Subversion |
|
Prerequisites ................................................................................................................. |
103 |
Basic Apache Configuration ............................................................................................. |
103 |
Authentication Options ................................................................................................... |
105 |
Authorization Options ..................................................................................................... |
108 |
Extra Goodies ................................................................................................................ |
113 |
Supporting Multiple Repository Access Methods ......................................................................... |
114 |
7. Advanced Topics ........................................................................................................................ |
116 |
Runtime Configuration Area .................................................................................................... |
116 |
Configuration Area Layout .............................................................................................. |
116 |
Configuration and the Windows Registry ............................................................................ |
117 |
Configuration Options ..................................................................................................... |
118 |
Properties ............................................................................................................................. |
121 |
Why Properties? ............................................................................................................ |
122 |
Manipulating Properties .................................................................................................. |
122 |
Special Properties ........................................................................................................... |
126 |
Automatic Property Setting .............................................................................................. |
132 |
Peg and Operative Revisions .................................................................................................... |
132 |
Externals Definitions .............................................................................................................. |
135 |
Vendor branches .................................................................................................................... |
136 |
General Vendor Branch Management Procedure .................................................................. |
137 |
svn_load_dirs.pl ............................................................................................................. |
138 |
Localization .......................................................................................................................... |
139 |
Understanding locales ..................................................................................................... |
140 |
Subversion's use of locales ............................................................................................... |
140 |
Subversion Repository URLs ................................................................................................... |
141 |
8. Developer Information ................................................................................................................. |
143 |
Layered Library Design ........................................................................................................... |
143 |
Repository Layer ........................................................................................................... |
144 |
Repository Access Layer ................................................................................................. |
148 |
Client Layer .................................................................................................................. |
150 |
Using the APIs ...................................................................................................................... |
151 |
The Apache Portable Runtime Library ............................................................................... |
151 |
URL and Path Requirements ............................................................................................ |
152 |
Using Languages Other than C and C++ ............................................................................. |
152 |
Inside the Working Copy Administration Area ............................................................................. |
154 |
The Entries File ............................................................................................................. |
154 |
Pristine Copies and Property Files ..................................................................................... |
155 |
WebDAV ............................................................................................................................. |
156 |
Programming with Memory Pools ............................................................................................. |
156 |
Contributing to Subversion ...................................................................................................... |
158 |
Join the Community ....................................................................................................... |
158 |
Get the Source Code ....................................................................................................... |
159 |
Become Familiar with Community Policies ......................................................................... |
159 |
Make and Test Your Changes ........................................................................................... |
160 |
Donate Your Changes ..................................................................................................... |
160 |
9. Subversion Complete Reference .................................................................................................... |
161 |
The Subversion Command Line Client: svn ................................................................................. |
161 |
svn Switches ................................................................................................................. |
161 |
svn Subcommands .......................................................................................................... |
164 |
svnadmin .............................................................................................................................. |
222 |
svnadmin Switches ......................................................................................................... |
222 |
svnadmin Subcommands ................................................................................................. |
223 |
svnlook ................................................................................................................................ |
236 |
svnlook Switches ........................................................................................................... |
236 |
svnlook ........................................................................................................................ |
237 |
svnserve ............................................................................................................................... |
252 |
svnserve Switches .......................................................................................................... |
252 |
svnversion ............................................................................................................................ |
253 |
vi
Version Control with Subversion |
|
mod_dav_svn ........................................................................................................................ |
255 |
A. Subversion for CVS Users ........................................................................................................... |
257 |
Revision Numbers Are Different Now ........................................................................................ |
257 |
Directory Versions ................................................................................................................. |
257 |
More Disconnected Operations ................................................................................................. |
258 |
Distinction Between Status and Update ...................................................................................... |
258 |
Branches and Tags ................................................................................................................. |
259 |
Metadata Properties ................................................................................................................ |
260 |
Conflict Resolution ................................................................................................................ |
260 |
Binary Files and Translation ..................................................................................................... |
260 |
Versioned Modules ................................................................................................................ |
260 |
Authentication ....................................................................................................................... |
261 |
Converting a Repository from CVS to Subversion ........................................................................ |
261 |
B. Troubleshooting ......................................................................................................................... |
262 |
Common Problems ................................................................................................................. |
262 |
Problems Using Subversion ............................................................................................. |
262 |
C. WebDAV and Autoversioning ...................................................................................................... |
268 |
Basic WebDAV Concepts ........................................................................................................ |
268 |
Just Plain WebDAV ....................................................................................................... |
268 |
DeltaV Extensions .......................................................................................................... |
268 |
Subversion and DeltaV ............................................................................................................ |
269 |
Mapping Subversion to DeltaV ......................................................................................... |
270 |
Autoversioning Support ................................................................................................... |
270 |
The mod_dav_lock Alternative ......................................................................................... |
271 |
Autoversioning Interoperability ................................................................................................ |
271 |
Win32 WebFolders ........................................................................................................ |
272 |
Mac OS X .................................................................................................................... |
272 |
Unix: Nautilus 2 ............................................................................................................ |
272 |
Linux davfs2 ................................................................................................................. |
273 |
D. Third Party Tools ....................................................................................................................... |
274 |
Clients and Plugins ................................................................................................................. |
274 |
Language Bindings ................................................................................................................. |
274 |
Repository Converters ............................................................................................................. |
275 |
Higher Level Tools ................................................................................................................. |
275 |
Repository Browsing Tools ...................................................................................................... |
275 |
E. Copyright ................................................................................................................................. |
277 |
vii
List of Figures |
|
1.1. Subversion's Architecture .......................................................................................................... |
3 |
2.1. A typical client/server system ..................................................................................................... |
8 |
2.2. The problem to avoid ................................................................................................................ |
9 |
2.3. The lock-modify-unlock solution ................................................................................................. |
10 |
2.4. The copy-modify-merge solution ................................................................................................. |
11 |
2.5. The copy-modify-merge solution (continued) ................................................................................ |
12 |
2.6. The repository's filesystem ......................................................................................................... |
13 |
2.7. The repository ......................................................................................................................... |
16 |
4.1. Branches of development ........................................................................................................... |
42 |
4.2. Starting repository layout ........................................................................................................... |
43 |
4.3. Repository with new copy .......................................................................................................... |
45 |
4.4. The branching of one file's history ............................................................................................... |
46 |
8.1. Files and directories in two dimensions ......................................................................................... |
145 |
8.2. Versioning time—the third dimension! ......................................................................................... |
145 |
viii
List of Tables |
|
2.1. Repository Access URLs ........................................................................................................... |
15 |
5.1. Repository Data-Store Comparison .............................................................................................. |
66 |
6.1. Network Server Comparison ....................................................................................................... |
93 |
8.1. A Brief Inventory of the Subversion Libraries ................................................................................ |
143 |
ix
List of Examples |
|
5.1. Using svnshell to Navigate the Repository .................................................................................... |
80 |
5.2. txn-info.sh (Reporting Outstanding Transactions) ........................................................................... |
82 |
6.1. A sample configuration for anonymous access. .............................................................................. |
109 |
6.2. A sample configuration for authenticated access. ............................................................................ |
110 |
6.3. A sample configuration for mixed authenticated/anonymous access. .................................................. |
110 |
6.4. Disabling path checks altogether ................................................................................................. |
112 |
7.1. Sample Registration Entries (.reg) File. ........................................................................................ |
117 |
8.1. Using the Repository Layer ........................................................................................................ |
146 |
8.2. Using the Repository Layer with Python ....................................................................................... |
152 |
8.3. A Simple Script to Check Out a Working Copy. ............................................................................. |
153 |
8.4. Contents of a Typical .svn/entries File .......................................................................................... |
154 |
8.5. Effective Pool Usage ................................................................................................................. |
157 |
x