Download: Version Control with Subversion For Subversion 1.7 (Compiled from r4526)

Version Control with Subversion For Subversion 1.7 (Compiled from r4526) Ben Collins-Sussman Brian W. Fitzpatrick C. Michael Pilato Version Control with Subversion: For Subversion 1.7: (Compiled from r4526) by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/2.0/ or send a letter to Creative Commons, 559...
Author: Thistarry Shared: 7/30/19
Downloads: 682 Views: 3967

Content

Version Control with Subversion For Subversion 1.7

(Compiled from r4526) Ben Collins-Sussman Brian W. Fitzpatrick C. Michael Pilato,

Version Control with Subversion: For Subversion 1.7: (Compiled from r4526)

by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.,

Table of Contents

Foreword ...xii Preface ... xiv What Is Subversion? ... xiv Is Subversion the Right Tool? ... xiv Subversion's History ... xv Subversion's Architecture ... xvi Subversion's Components ... xviii What's New in Subversion ... xviii Audience ... xix How to Read This Book ... xix Organization of This Book ... xx This Book Is Free ... xxi Acknowledgments ... xxii 1. Fundamental Concepts ... 1 Version Control Basics ... 1 The Repository ... 1 The Working Copy ... 2 Versioning Models ... 2 Version Control the Subversion Way ... 7 Subversion Repositories ... 7 Revisions ... 7 Addressing the Repository ... 8 Subversion Working Copies ... 9 Summary ... 14 2. Basic Usage ... 15 Help! ... 15 Getting Data into Your Repository ... 16 Importing Files and Directories ... 16 Recommended Repository Layout ... 17 What's In a Name? ... 17 Creating a Working Copy ... 18 Basic Work Cycle ... 19 Update Your Working Copy ... 20 Make Your Changes ... 20 Review Your Changes ... 22 Fix Your Mistakes ... 25 Resolve Any Conflicts ... 26 Commit Your Changes ... 33 Examining History ... 34 Examining the Details of Historical Changes ... 34 Generating a List of Historical Changes ... 36 Browsing the Repository ... 38 Fetching Older Repository Snapshots ... 40 Sometimes You Just Need to Clean Up ... 41 Disposing of a Working Copy ... 42 Recovering from an Interruption ... 42 Dealing with Structural Conflicts ... 42 An Example Tree Conflict ... 43 Summary ... 48 3. Advanced Topics ... 49 Revision Specifiers ... 49 Revision Keywords ... 49 Revision Dates ... 50 iv, Version Control with Subversion Peg and Operative Revisions ... 51 Properties ... 55 Why Properties? ... 56 Manipulating Properties ... 57 Properties and the Subversion Workflow ... 60 Automatic Property Setting ... 62 File Portability ... 63 File Content Type ... 63 File Executability ... 64 End-of-Line Character Sequences ... 65 Ignoring Unversioned Items ... 66 Keyword Substitution ... 69 Sparse Directories ... 72 Locking ... 77 Creating Locks ... 78 Discovering Locks ... 80 Breaking and Stealing Locks ... 81 Lock Communication ... 83 Externals Definitions ... 84 Changelists ... 90 Creating and Modifying Changelists ... 90 Changelists As Operation Filters ... 92 Changelist Limitations ... 94 Network Model ... 94 Requests and Responses ... 94 Client Credentials ... 95 Summary ... 97 4. Branching and Merging ... 99 What's a Branch? ... 99 Using Branches ... 99 Creating a Branch ... 101 Working with Your Branch ... 102 The Key Concepts Behind Branching ... 105 Basic Merging ... 105 Changesets ... 105 Keeping a Branch in Sync ... 106 Reintegrating a Branch ... 111 Mergeinfo and Previews ... 113 Undoing Changes ... 116 Resurrecting Deleted Items ... 117 Advanced Merging ... 119 Cherrypicking ... 119 Merge Syntax: Full Disclosure ... 121 Merges Without Mergeinfo ... 122 More on Merge Conflicts ... 123 Blocking Changes ... 125 Keeping a Reintegrated Branch Alive ... 126 Merge-Sensitive Logs and Annotations ... 127 Noticing or Ignoring Ancestry ... 129 Merges and Moves ... 130 Blocking Merge-Unaware Clients ... 130 The Final Word on Merge Tracking ... 131 Traversing Branches ... 132 Tags ... 134 Creating a Simple Tag ... 134 Creating a Complex Tag ... 134 Branch Maintenance ... 135 Repository Layout ... 135 v, Version Control with Subversion Data Lifetimes ... 136 Common Branching Patterns ... 137 Release Branches ... 137 Feature Branches ... 138 Vendor Branches ... 138 General Vendor Branch Management Procedure ... 139 svn_load_dirs.pl ... 141 To Branch or Not to Branch? ... 142 Summary ... 143 5. Repository Administration ... 145 The Subversion Repository, Defined ... 145 Strategies for Repository Deployment ... 146 Planning Your Repository Organization ... 146 Deciding Where and How to Host Your Repository ... 148 Choosing a Data Store ... 149 Creating and Configuring Your Repository ... 152 Creating the Repository ... 152 Implementing Repository Hooks ... 153 Berkeley DB Configuration ... 154 FSFS Configuration ... 154 Repository Maintenance ... 155 An Administrator's Toolkit ... 155 Commit Log Message Correction ... 159 Managing Disk Space ... 159 Berkeley DB Recovery ... 163 Migrating Repository Data Elsewhere ... 164 Filtering Repository History ... 168 Repository Replication ... 171 Repository Backup ... 178 Managing Repository UUIDs ... 179 Moving and Removing Repositories ... 180 Summary ... 181 6. Server Configuration ... 182 Overview ... 182 Choosing a Server Configuration ... 183 The svnserve Server ... 183 svnserve over SSH ... 183 The Apache HTTP Server ... 184 Recommendations ... 184 svnserve, a Custom Server ... 185 Invoking the Server ... 185 Built-in Authentication and Authorization ... 189 Using svnserve with SASL ... 191 Tunneling over SSH ... 193 SSH Configuration Tricks ... 195 httpd, the Apache HTTP Server ... 196 Prerequisites ... 197 Basic Apache Configuration ... 197 Authentication Options ... 199 Authorization Options ... 202 Protecting network traffic with SSL ... 205 Extra Goodies ... 207 Path-Based Authorization ... 214 High-level Logging ... 219 Server Optimization ... 221 Data Caching ... 221 Network Compression of Data ... 222 Supporting Multiple Repository Access Methods ... 222 vi, Version Control with Subversion 7. Customizing Your Subversion Experience ... 225 Runtime Configuration Area ... 225 Configuration Area Layout ... 225 Configuration and the Windows Registry ... 226 Configuration Options ... 227 Localization ... 232 Understanding Locales ... 233 Subversion's Use of Locales ... 233 Using External Editors ... 234 Using External Differencing and Merge Tools ... 235 External diff ... 236 External diff3 ... 237 External merge ... 238 Summary ... 239 8. Embedding Subversion ... 240 Layered Library Design ... 240 Repository Layer ... 241 Repository Access Layer ... 244 Client Layer ... 245 Using the APIs ... 246 The Apache Portable Runtime Library ... 246 Functions and Batons ... 247 URL and Path Requirements ... 247 Using Languages Other Than C and C++ ... 247 Code Samples ... 248 Summary ... 254 9. Subversion Complete Reference ... 255 svn—Subversion Command-Line Client ... 255 svn Options ... 255 svn Subcommands ... 262 svnadmin—Subversion Repository Administration ... 339 svnadmin Options ... 339 svnadmin Subcommands ... 340 svnlook—Subversion Repository Examination ... 363 svnlook Options ... 363 svnlook Subcommands ... 365 svnsync—Subversion Repository Mirroring ... 385 svnsync Options ... 385 svnsync Subcommands ... 387 svnrdump—Remote Subversion Repository Data Migration ... 395 svnrdump Options ... 395 svnrdump Subcommands ... 396 svnserve—Custom Subversion Server ... 399 svnserve Options ... 400 svndumpfilter—Subversion History Filtering ... 401 svndumpfilter Options ... 401 svndumpfilter Subcommands ... 402 svnversion—Subversion Working Copy Version Info ... 407 mod_dav_svn—Subversion Apache HTTP Server Module ... 409 mod_authz_svn—Subversion Apache HTTP Authorization Module ... 412 Subversion Properties ... 413 Versioned Properties ... 413 Unversioned Properties ... 414 Repository Hooks ... 415 A. Subversion Quick-Start Guide ... 425 Installing Subversion ... 425 High-Speed Tutorial ... 426 B. Subversion for CVS Users ... 428 vii, Version Control with Subversion Revision Numbers Are Different Now ... 428 Directory Versions ... 428 More Disconnected Operations ... 429 Distinction Between Status and Update ... 429 Status ... 429 Update ... 430 Branches and Tags ... 430 Metadata Properties ... 431 Conflict Resolution ... 431 Binary Files and Translation ... 431 Versioned Modules ... 431 Authentication ... 432 Converting a Repository from CVS to Subversion ... 432 C. WebDAV and Autoversioning ... 433 What Is WebDAV? ... 433 Autoversioning ... 434 Client Interoperability ... 435 Standalone WebDAV Applications ... 436 File-Explorer WebDAV Extensions ... 437 WebDAV Filesystem Implementation ... 438 D. Copyright ... 440 Index ... 445 viii,

List of Figures

1. Subversion's architecture ... xvi 1.1. A typical client/server system ... 1 1.2. The problem to avoid ... 2 1.3. The lock-modify-unlock solution ... 3 1.4. The copy-modify-merge solution ... 5 1.5. The copy-modify-merge solution (continued) ... 5 1.6. Tree changes over time ... 7 1.7. The repository's filesystem ... 11 4.1. Branches of development ... 99 4.2. Starting repository layout ... 100 4.3. Repository with new copy ... 101 4.4. The branching of one file's history ... 103 8.1. Files and directories in two dimensions ... 242 8.2. Versioning time—the third dimension! ... 243 ix,

List of Tables

1.1. Repository access URLs ... 8 2.1. Common log requests ... 36 4.1. Branching and merging commands ... 143 5.1. Repository data store comparison ... 149 6.1. Comparison of subversion server options ... 182 C.1. Common WebDAV clients ... 435 x,

List of Examples

4.1. Merge-tracking gatekeeper start-commit hook script ... 131 5.1. txn-info.sh (reporting outstanding transactions) ... 160 5.2. Mirror repository's pre-revprop-change hook script ... 172 5.3. Mirror repository's start-commit hook script ... 173 6.1. A sample svnserve launchd job definition ... 188 6.2. A sample configuration for anonymous access ... 203 6.3. A sample configuration for authenticated access ... 204 6.4. A sample configuration for mixed authenticated/anonymous access ... 204 6.5. Disabling path checks altogether ... 205 7.1. Sample registration entries (.reg) file ... 226 7.2. diffwrap.py ... 236 7.3. diffwrap.bat ... 237 7.4. diff3wrap.py ... 237 7.5. diff3wrap.bat ... 238 7.6. mergewrap.py ... 238 7.7. mergewrap.bat ... 239 8.1. Using the repository layer ... 248 8.2. Using the repository layer with Python ... 250 8.3. A Python status crawler ... 252 xi,

Foreword

Karl Fogel Chicago, March 14, 2004. A bad Frequently Asked Questions (FAQ) sheet is one that is composed not of the questions people actually ask, but of the ques- tions the FAQ's author wishes people would ask. Perhaps you've seen the type before: Q: How can I use Glorbosoft XYZ to maximize team productivity? A: Many of our customers want to know how they can maximize productivity through our patented office group- ware innovations. The answer is simple. First, click on the File menu, scroll down to In- crease Productivity, then… The problem with such FAQs is that they are not, in a literal sense, FAQs at all. No one ever called the tech support line and asked, “How can we maximize productivity?” Rather, people asked highly specific questions, such as “How can we change the calendar- ing system to send reminders two days in advance instead of one?” and so on. But it's a lot easier to make up imaginary Frequently Asked Questions than it is to discover the real ones. Compiling a true FAQ sheet requires a sustained, organized effort: over the lifetime of the software, incoming questions must be tracked, responses monitored, and all gathered into a coherent, searchable whole that reflects the collective experience of users in the wild. It calls for the patient, observant attitude of a field naturalist. No grand hypothesizing, no visionary pronouncements here—open eyes and accurate note-taking are what's needed most. What I love about this book is that it grew out of just such a process, and shows it on every page. It is the direct result of the au- thors' encounters with users. It began with Ben Collins-Sussman's observation that people were asking the same basic questions over and over on the Subversion mailing lists: what are the standard workflows to use with Subversion? Do branches and tags work the same way as in other version control systems? How can I find out who made a particular change? Frustrated at seeing the same questions day after day, Ben worked intensely over a month in the summer of 2002 to write The Sub- version Handbook, a 60-page manual that covered all the basics of using Subversion. The manual made no pretense of being com- plete, but it was distributed with Subversion and got users over that initial hump in the learning curve. When O'Reilly decided to publish a full-length Subversion book, the path of least resistance was obvious: just expand the Subversion handbook. The three coauthors of the new book were thus presented with an unusual opportunity. Officially, their task was to write a book top-down, starting from a table of contents and an initial draft. But they also had access to a steady stream—indeed, an uncontrol- lable geyser—of bottom-up source material. Subversion was already in the hands of thousands of early adopters, and those users were giving tons of feedback, not only about Subversion, but also about its existing documentation. During the entire time they wrote this book, Ben, Mike, and Brian haunted the Subversion mailing lists and chat rooms incessantly, carefully noting the problems users were having in real-life situations. Monitoring such feedback was part of their job descriptions at CollabNet anyway, and it gave them a huge advantage when they set out to document Subversion. The book they produced is grounded firmly in the bedrock of experience, not in the shifting sands of wishful thinking; it combines the best aspects of user manual and FAQ sheet. This duality might not be noticeable on a first reading. Taken in order, front to back, the book is simply a straightforward description of a piece of software. There's the overview, the obligatory guided tour, the chapter on administrative configuration, some advanced topics, and of course, a command reference and troubleshooting guide. Only when you come back to it later, seeking the solution to some specific problem, does its authenticity shine out: the telling details that can only result from encounters with the unexpected, the examples honed from genuine use cases, and most of all the sensitivity to the user's needs and the user's point of view. Of course, no one can promise that this book will answer every question you have about Subversion. Sometimes the precision with which it anticipates your questions will seem eerily telepathic; yet occasionally, you will stumble into a hole in the community's knowledge and come away empty-handed. When this happens, the best thing you can do is email