Download from Wow! eBook <www.wowebook.com> What Readers Are Saying About Pragmatic Guide to Subversion Mike h as been around the block with Subversion and knows the toolset intimately. Just as importantly, he’ s seen firsthand how it’s used on real projects. Those two aspects come together in this book with the fundamen- tals of source control with Subversion, g uided by r eal-world, pragmatic (of course!) e x p e r i e n c e . As a Subversion user and occasional n oob, this is the book I w an t t o guide me day to d ay and dig me out of t hose irksome holes. Jim W e b b e r Author, REST i n Practice I really like the organization of the b ook. I f ound Pragmatic Guide to S ub- version t o be v e r y easy to read, and it really gets the information across in an engaging w ay. This book is c lear, concise, and comprehensive. It’s an indispensable reference for anyone wo rk i ng with Subversion. Ian Bourke Independent software developer, UK A good digest of S ubversion’s capabilities. The author’ s writing style is terse yet conversational, and the b ook progressed nicely from basic t opics to those more adv anced. Overall, I think the book is a n e x c e l l e n t follow-up to Pragmatic V e r s i o n Control Using Subversion. Graham Nash Retlang, Message-based concurrency in .NET This is a book wo rth ha ving since the “full” Pragmatic Subversion book i s too big for e v e r y d e veloper on a team t o read. I was a fan of Mike’ s original Subversion book, a nd he’s carried on the style into this p ocket reference. This is a book I r ecommend. Mike Roberts Senior software e ngineer, DRW T r a d i n g Group Pragmatic Guide to Subversion has e v e r y t h i n g I needed t o get u p and run- ning with SVN on my Mac. Being ne w to Mac OS X, it w as a welcome s ur- prise to have e x a m p l e s in multiple operating systems. Michael Raczynski Software a rchitect, Canada Download from Wow! eBook <www.wowebook.com> Pragmatic Guide to Subversion Mike Mason The P ragmatic Bookshelf Raleigh, North Carolina Dallas, T e x a s Download from Wow! eBook <www.wowebook.com> Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this b ook, and The P ragmatic Pro- grammers, LLC was aw a re of a trademark claim, the d esignations have been printed in initial capital letters or in a ll capitals. The P ragmatic Starter Kit, T he Pragmatic P rogrammer, Pragmatic Programming, Pragmatic Bookshelf and the linking g device are trademarks o f The Pragmatic Programmers, LLC. Every precaution wa s taken in the preparation o f this book. However, the publisher assumes no responsibility f or errors or o missions, or for damages that may result from the use o f information (including p rogram listings) contained h erein. Our Pragmatic courses, workshops, and other products can help you and your team create better software and have more fun. F o r more information, as well as the latest Pragmatic titles, please visit u s at h ttp://www.pragprog.com. The team that p roduced this b ook includes: Editor: Jackie Carter Indexing: Potomac I ndexing, LLC Copy edit: Kim W i m p s e t t Layout: Steve Peter Production: Janet Furlow Customer support: Ellie Callahan International: Juliet Benda Copyright © 2010 Pragmatic P rogrammers, LLC. All r ights reserved. No part of this publication m ay b e reproduced, stored in a retrieval s ystem, or transmitted, in an y form, or by any means, electronic, mechanical, photocopying, recording, or o therwise, without the prior consent of the publisher . Printed in the United States of America. ISBN-10: 1-934356-61-1 ISBN-13: 978-1-934356-61-6 Printed o n acid-free p aper . P1.0 printing, October 2 010 V e r s i o n : 2010-11-12 Download from Wow! eBook <www.wowebook.com> Contents Acknowledgments 8 Introduction 9 Who I s This Book F o r ? . . . . . . . . . . . . . . . . . . . . 10 How to Read This Book . . . . . . . . . . . . . . . . . . . . 11 Subversion V e r s i o n s . . . . . . . . . . . . . . . . . . . . . . 12 Online Resources . . . . . . . . . . . . . . . . . . . . . . . 12 I Getting Started 13 T a s k 1. Installing a Command-Line Client 16 T a s k 2. Installing a Graphical Client on W i n d o w s 18 T a s k 3. Installing a Graphical Client on Mac OS X 20 T a s k 4. Creating a Local Repository 22 T a s k 5. Creating an Empty Pr oject 24 T a s k 6. Creating a Project from a n Existing S ource T r e e 26 II W o r k i n g with Subversion 28 T a s k 7. Checking Out a W o r k i n g Copy 32 T a s k 8. Seeing What Y o u ’ v e Changed 34 T a s k 9. Seeing What Y o u ’ v e Changed Using T o r t o i s e 36 T a s k 10. Seeing What Y o u ’ v e Changed Using Cornerstone 38 T a s k 11. Committing Changes 40 T a s k 12. Adding Files and Directories 42 Download from Wow! eBook <www.wowebook.com> CONTENTS 6 T a s k 13. Removing Files and Directories 44 T a s k 14. Moving a nd Renaming Files and Directories 46 T a s k 15. Reverting W o r k i n g Copy Changes 48 T a s k 16. Ignoring Files 50 III W o r k i n g with a T e a m 52 T a s k 17. Updating to the Latest Revision 56 T a s k 18. Handling Conflicts 58 T a s k 19. Handling Conflicts Using T o r t o i s e 60 T a s k 20. Handling Conflicts Using Cornerstone 62 IV Using the History 64 T a s k 21. V i e w i n g the Log 66 T a s k 22. Detective W o r k with svn blame 68 T a s k 23. Reverting a Committed Revision 70 V Branching, Merging, and T a g g i n g 72 T a s k 24. Creating a Branch 78 T a s k 25. Switching t o a Branch 80 T a s k 26. Merging Changes fr om T r u n k to Branch 82 T a s k 27. Using Change T r a c k i n g 84 T a s k 28. T a g g i n g a Release 86 VI File Locking 88 T a s k 29. Enabling File Locking 9 2 T a s k 30. Obtaining a Lock 94 T a s k 31. Releasing a Lock 96 T a s k 32. Breaking Someone Else’s Lock 98 Report erratum this copy is (P1.0 printing, October 2010) Download from Wow! eBook <www.wowebook.com> CONTENTS 7 VII Setting Up a Server 100 T a s k 33. Installing Subversion S erver 104 T a s k 34. Creating a Repository 106 T a s k 35. Installing Subversion S erver on W i n d o w s 108 T a s k 36. Using Third-Party Subversion Hosting 110 T a s k 37. Migrating a CVS Repository 112 T a s k 38. Backing Up a nd Restoring 114 T a s k 39. P e r f o r m i n g Full W e e k l y Backups 1 16 T a s k 40. P e r f o r m i n g Incremental Daily Backups 118 T a s k 41. Securing a Repository 120 T a s k 42. Using Repository Hooks 122 VIII Advanced T o p i c s 124 T a s k 43. W o r k i n g with Properties 126 T a s k 44. Using Externals 128 T a s k 45. Organizing Multiple Projects 130 T a s k 46. Storing Third-Party Code 132 T a s k 47. W o r k i n g Directly with t he Repository 134 T a s k 48. Using P at ch Files 136 A Bibliography 1 38 Index 139 Report erratum this copy is (P1.0 printing, October 2010) Download from Wow! eBook <www.wowebook.com> Acknowledgments Every book—even a shorter one like this Pragmatic Guide—represents an incredible amount of w ork by a large group of p eople. As a n author , my con- tribution is only a f raction of the ef fort that’s required to get a book into the hands of readers, and I’d like to thank e v e r y o n e else involved. First and foremost, I’d like to thank my f amily for supporting me while writ- ing another book. I’m a ne w d ad with a young son at home, and despite my best efforts to write faster, our daughter arrived too before I finished the book. So, to my wife, Michelle, and her mom, P a t , thanks for taking care o f the kids and l etting me have those Sundays in the office writing the book. T o Ben and Natalie, t hanks for not being too upset when “Daddy wo rki ng! ” I promise to always come home. Next, the Pragmatic Guide series idea came from T r a v i s Swicegood, a uthor of the e x c e l l e n t Pragmatic V e r s i o n Control Using Git [Swi08]. I really liked the idea of a “get up to speed fa st ” Subversion book, so thank you, T r a v i s . The folks at Pragmatic Bookshelf were super-awesome to wor k with as usual, although the operation i s a lot bigger t han when I did the original Subversion book fi v e years ago. T o Jackie Carter, my editor, thanks for ke ep in g me on track and (nicely) pushing me to finish. I always felt that you had lots of time for me, and the book is much better as a result. T o Dave and Andy , thanks for b u i l d i n g a nontraditional publishing company that creates great books and gives authors a good d eal. A small army of people helped with the technical content in the book. T o my reviewers, Rob Baillie, Ian Bourke, K e v i n Gisi, Leesa Hicks, Michael Raczynski, Mike Roberts, and Graham Nash, thank you v e r y much indeed. Y o u r feedback has made this book better, and your encouraging wo r ds helped me finish the writing. T o my fellow ThoughtWorks authors, especially Martin F o w l e r and Jonathan McCracken, thank you for being a sounding board while I wor ked on the book. Finally , I’d like to thank you, the reader, for choosing this book. I hope you enjoy reading it—I certainly enjoyed writing i t. Download from Wow! eBook <www.wowebook.com> Intr oduction Subversion is a wildly popular open source v e r s i o n control system, a v a i l - able for free o v e r the Internet. Subversion is widely considered the de f acto standard 1 for v e r s i o n control tools, e v e n though such a thing is difficult to measure, and as a developer, you are likely to encounter Subversion as part of your w ork . Subversion is a mature, fully f eatured system that is commonly used by both commercial and open source development teams. Y o u can b u y commercial support and consulting services to help you install, configure, and use Sub- v e r s i o n . If you don’t wa nt the hassle of running a Subversion server, you can get a third party t o do it for you, a t a low cost o r e v e n for f ree. Subversion i s a centralized v e r s i o n control system, meaning that i t uses a cen- tral server t o store files and enable team collaboration. Clients can wo rk dis- connected from the network—on an airplane, for e x a m p l e — a n d need a net- wor k connection only if they a ctually wan t to commit changes to the server. This traditional centralized model assumes that development teams have r ea- sonable network connectivity to the server. In contrast, some newer decen- tralized v e r s i o n control systems use a model where each user acts kind of like a server. Users can swap changes between each other without needing a cen- tral server. Most organizations will be fine with the centralized model used by Subversion, b u t it’s wor th being a w a r e that other collaboration styles are possible. Subversion is popular because it has all the features that programmers need and very few e x t r a bells and whistles. It just d oes v e r s i o n control, and it does it well. Subversion can track vers i o n information for directories and metadata, a s well as files. T r e a t i n g directories as first-class objects means that Subversion can track history across directory moves a nd renames, unlike some older v e r s i o n 1. Determining the ex a ct market share for Subversion is difficult, b u t several online polls rate S ubversion more popular than any other ve r si on control tool. Martin Fow l er suggests that within the Agile/XP community , only Subversion, Git, and Mercurial would be recommended: http://martinfowler .com/bliki/VersionControlTools.html. Download from Wow! eBook <www.wowebook.com> WHOIS THISBOOKFOR? 10 control systems. Every file and directory c an have arbitrary metadata associ- ated with i t using Subversion properties. Committing a change is atomic, similar to committing to a database. Either the whole commit succeeds or is rolled back; other users never see a half- finished commit. As part of the atomic commit process, Subversion groups all your changes into a r e v i s i o n (sometimes called a c h a n g e s e t ) and assigns a r e v i s i o n number to the change, unlike older systems that apply a revision number to each individual file. By grouping changes to multiple files into a single logical unit, developers are able to better organize and track their changes. Subversion has cheap branches and tags that can be created almost instantly. Branches are used to distinguish different lines of development, most com- monly to separate code that is in production vs. code that is being activ ely developed. T a g s are used t o “mark” the state of the code at a particular point in time so that state can be re-created later. Subversion also supports merge tracking, which helps automatically merge changes between b ranches. Subversion is a truly multiplatform tool. Y o u can run Subversion on W i n - dows, Linux, OS X, and many other flav ors of Unix. Each of these operating systems is considered a first-class platform by the Subversion developers, and you can run a production-strength server on any of them. A Subversion client can talk to a Subversion server e v e n if the client and server are running on different operating systems. This is good news for anyone trying to fit Sub- v e r s i o n into their e x i s t i n g infrastructure. F o r those e v a l u a t i n g Subversion, the wide choice of o perating system makes t hings much e asier since you can run a server on pretty much any spare machine. Who Is This Book For? Most developers have at least some e x p e r i e n c e with a source control tool and are e x p e c t e d to fluidly switch between tools depending on where they are wor k in g . This book w as written to bridge the gap between knowing some- thing about v e r s i o n control and knowing about Subversion specifically . Pragmatic Guide to Subversion will quickly get you up to speed on Subver- sion. W e don’t spend a lot of time covering the philosophy of v e r s i o n control or trying to persuade you i t’s a g ood idea to store your files somewhere safe. If you are interested in a broader discussion of v e r s i o n control concepts and some of the reasoning behind what we do, check out Pragmatic V e r s i o n Con- trol Using Subversion [Mas06], 2 my previous book. 2. http://pragprog.com/titles/svn2/ Report erratum this copy is (P1.0 printing, October 2010) Download from Wow! eBook <www.wowebook.com> [...]... empty directory, you need to tell Subversion to initialize a repository in that directory Command-line users should use the svnadmin command to achieve this Tortoise users should right-click the directory to initialize a repository Cornerstone users should use the Cornerstone GUI to create the repository Once you have initialized the repository, you can start using it, but you’ll need to tell Subversion. .. use a shorthand to denote choosing Tortoise menu options, rather than showing screenshots all the time To indicate that you should right-click to get the context menu and then click TortoiseSVN and then Show Log, we will use the abbreviation TortoiseSVN > Show Log Tortoise shows its context-sensitive options both immediately on the context menu and within the TortoiseSVN flyout menu Tortoise lets you... window and get context-sensitive Subversion options If you right-click in a directory that isn’t a Subversion working copy, Tortoise will offer to let you check it out from a repository If you right-click a directory that is a working copy, Tortoise will offer to let you update or commit If you right-click a file inside a working copy, Tortoise will offer to show history for the file, and so on Throughout... where to find the repository This is where the repository base URL is needed The base URL for a local repository always starts with file:// and ends with the path within the file system to get to your repository directory You can turn a local repository into a networked repository by running a Subversion server and pointing it at the repository directory You can find more details in Task 33, Installing Subversion. .. directory, and choose TortoiseSVN > Create repository here The base URL for your local repository is file:///C: /Subversion/ Repos Create a local repository using Cornerstone Choose File > Add Repository , or click the plus icon in the repository source list Select the File Repository button at the top, and click Create a New Repository Click the Where drop-down, and choose the folder in which you want to. .. Use Tortoise to create directories Right-click inside any Explorer window, and choose TortoiseSVN > Repo-browser Enter the URL for your repository, for example http://svn mycompany.com/ Tortoise will show you a repository browser where you can manipulate your repository Right-click, and choose “Create folder” as necessary to create all the directories you need for your project Use Cornerstone to create... Working with Subversion discusses daily workflow when using Subversion You’ll learn how to check out from a repository, examine or undo your changes, and commit to the repository • Part III: Working with a Team covers how to use Subversion in a team setting, how to stay in sync with your team, and how to resolve conflicts • Part IV: Using the History shows you Subversion s powerful history tools so you... repository browser, and choose Import In the file dialog box, browse to the directory you want to import, select it, and click the Open button In the Import As text box, enter myproject/trunk as the directory to import to Click Import, enter a log message, and Cornerstone will import your files Use the repository browser to navigate to your newly imported trunk directory Create tags and branches directories... If you are trying Subversion for yourself and need to set up a local repository for testing, see Task 4, Creating a Local Repository, on page 22 Report erratum Download from Wow! eBook this copy is (P1.0 printing, October 2010) 18 I NSTALLING A G RAPHICAL C LIENT ON W INDOWS Install the Tortoise graphical client Visit tortoisesvn.net,5 and download TortoiseSVN Tortoise is integrated... tree using Tortoise Using Windows Explorer, right-click the directory you want to import, and choose TortoiseSVN > Import Enter the repository URL for your project (make sure to include the trunk directory at the end of the URL), and enter a message describing what you’re importing Click OK to complete the import Import the whole tree using Cornerstone Select your repository from the repository source . information on how to store multiple projects in a single Subversion repository and how to store t hird-party c ode in y our o w n repository. Subversion V e. r s i o n control and knowing about Subversion specifically . Pragmatic Guide to Subversion will quickly get you up to speed on Subver- sion. W e don’t