Table Of ContentWhat readers are saying about
Pragmatic Version Control using Subversion
I expected a lot, but you surprised me with even more. Hav-
ing used CVS for years I hesitated to try Subversion until
now, although I knew it would solve many of the shortcom-
ings of CVS. After reading your book, my excuses to stay
with CVS disappeared. Oh, and coming from the Pragmatic
Bookshelf this book is fun to read too. Thanks Mike.
Steffen Gemkow
Managing Director, ObjectFab GmbH
I’m a long-time user of CVS and I’ve been skeptical of Sub-
version, wondering if it would ever be “ready for prime time.”
Until now. Thanks to Mike Mason for writing a clear, con-
cise, gentle introduction to this new tool. After reading this
book, I’m actually excited about the possibilities for version
control that Subversion brings to the table.
David Rupp
Senior SoftwareEngineer, Great-West Life & Annuity
This was exactly the Subversion book I was waiting for. As
a long-time Perforce and CVS user and administrator, and
in my role as an agile tools coach, I wanted a compact book
that told me just what I needed to know. This is it.
Within a couple of hours I was up and running against
remote Subversion servers, and setting up my own local
servers too. Mike uses a lot of command-line examples to
guide the reader, and as a Windows user I was worried at
first. My fears were unfounded though—Mike’s examples
were so clear that I think I’ll stick to using the command line
from now on! I thoroughly recommend this book to anyone
getting started using or administering Subversion.
Mike Roberts
Project co-Lead, CruiseControl.NET
Pragmatic Version Control
using Subversion, 2nd Edition
Mike Mason
The Pragmatic Bookshelf
Raleigh,NorthCarolina Dallas,Texas
(cid:8) (cid:9) (cid:10) (cid:11) (cid:12) (cid:10) (cid:13) (cid:14) (cid:15)
(cid:0) (cid:1) (cid:1) (cid:2) (cid:3) (cid:4) (cid:5) (cid:6) (cid:7)
Many of the designations used by manufacturers and sellers to distinguish
theirproductsareclaimedastrademarks. Wherethosedesignationsappear
inthisbook,andThePragmaticProgrammers,LLCwasawareofatrademark
claim, the designations have been printed in initial capital letters or in all
capitals. The Pragmatic Starter Kit, The Pragmatic Programmer, Pragmatic
Programming, PragmaticBookshelfandthe linkingg devicearetrademarks
ofThePragmaticProgrammers,LLC.
Every precaution was taken in the preparation of this book. However, the
publisherassumesnoresponsibilityforerrorsoromissions,orfordamages
thatmayresultfromtheuseofinformation(includingprogramlistings)con-
tainedherein.
Our Pragmatic courses, workshops, and other products can help you and
yourteamcreatebettersoftwareandhavemore fun. Formore information,
aswellasthelatestPragmatictitles,pleasevisitusat
http://www.pragmaticprogrammer.com
Copyright©2006ThePragmaticProgrammersLLC.
Allrightsreserved.
Nopartof thispublication maybe reproduced, storedin aretrievalsystem,
ortransmitted,inanyform,orbyanymeans,electronic,mechanical,photo-
copying,recording,orotherwise,withoutthepriorconsentofthepublisher.
PrintedintheUnitedStatesofAmerica.
ISBN0-9776166-5-7
Printedonacid-freepaperwith85%recycled,30%post-consumercontent.
Firstprinting,May2006
Version: 2006-5-12
Contents
Preface viii
1 Introduction 1
1.1 Version Control in Action . . . . . . . . . . . . . 2
1.2 Road Map . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Why Choose Subversion . . . . . . . . . . . . . . 6
2 What is Version Control? 9
2.1 The Repository . . . . . . . . . . . . . . . . . . . 9
2.2 What Should We Store? . . . . . . . . . . . . . . 11
2.3 Working Copies and Manipulating Files . . . . . 12
2.4 Projects, Directories, and Files . . . . . . . . . . 15
2.5 WhereDo Versions Come In? . . . . . . . . . . . 16
2.6 Tags . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.7 Branches . . . . . . . . . . . . . . . . . . . . . . 19
2.8 Merging . . . . . . . . . . . . . . . . . . . . . . . 22
2.9 Locking Options . . . . . . . . . . . . . . . . . . 23
2.10 Configuration Management (CM) . . . . . . . . . 26
3 Getting Started with Subversion 28
3.1 Installing Subversion . . . . . . . . . . . . . . . 28
3.2 Creating a Repository . . . . . . . . . . . . . . . 33
3.3 Creating a Simple Project . . . . . . . . . . . . . 34
3.4 Startingto Work with a Project . . . . . . . . . . 37
3.5 Making Changes . . . . . . . . . . . . . . . . . . 39
3.6 Updating the Repository . . . . . . . . . . . . . . 41
3.7 When Worlds Collide . . . . . . . . . . . . . . . . 44
3.8 Conflict Resolution . . . . . . . . . . . . . . . . . 47
CONTENTS vi
4 How To... 52
4.1 Our Basic Philosophy . . . . . . . . . . . . . . . 53
4.2 Important Steps When Using Version Control . 53
5 Accessing a Repository 55
5.1 Network Protocols . . . . . . . . . . . . . . . . . 55
5.2 Choosing a Networking Option . . . . . . . . . . 60
6 Common Subversion Commands 62
6.1 Checking Things Out . . . . . . . . . . . . . . . 62
6.2 Keeping Up-to-Date . . . . . . . . . . . . . . . . 64
6.3 Adding Files and Directories . . . . . . . . . . . 66
6.4 Properties . . . . . . . . . . . . . . . . . . . . . . 66
6.5 Copying and Moving Files and Directories . . . 75
6.6 Seeing What Has Changed . . . . . . . . . . . . 80
6.7 Handling Merge Conflicts . . . . . . . . . . . . . 86
6.8 Committing Changes . . . . . . . . . . . . . . . 91
6.9 Examining Change History . . . . . . . . . . . . 91
6.10 Removing a Change . . . . . . . . . . . . . . . . 95
7 File Locking and Binary Files 99
7.1 File Locking Overview . . . . . . . . . . . . . . . 99
7.2 File Locking in Practice . . . . . . . . . . . . . . 100
7.3 When to use Locking. . . . . . . . . . . . . . . . 106
8 Organizing Your Repository 107
8.1 A Simple Project . . . . . . . . . . . . . . . . . . 107
8.2 Multiple Projects . . . . . . . . . . . . . . . . . . 108
8.3 Multiple Repositories . . . . . . . . . . . . . . . 109
9 Using Tags and Branches 111
9.1 Tags and Branches. . . . . . . . . . . . . . . . . 112
9.2 Creating a Release Branch . . . . . . . . . . . . 115
9.3 Working in a Release Branch . . . . . . . . . . . 117
9.4 Generating a Release . . . . . . . . . . . . . . . 119
9.5 Fixing Bugs in a Release Branch . . . . . . . . . 121
9.6 Developer Experimental Branches . . . . . . . . 124
9.7 Working with Experimental Code . . . . . . . . 126
9.8 Merging the Experimental Branch . . . . . . . . 126
CONTENTS vii
10 Creating a Project 128
10.1 Creating the Initial Project . . . . . . . . . . . . 129
10.2 Structurewithin the Project . . . . . . . . . . . 131
10.3 Sharing Code between Projects . . . . . . . . . . 135
11 Third-Party Code 141
11.1 Binary Libraries . . . . . . . . . . . . . . . . . . 141
11.2 Libraries with Source Code . . . . . . . . . . . . 144
11.3 Keyword Expansion during Imports . . . . . . . 150
A Install, Network, Secure, and Administer 151
A.1 Installing Subversion . . . . . . . . . . . . . . . 151
A.2 Networking with svnserve . . . . . . . . . . . . . 153
A.3 Networking with svn+ssh . . . . . . . . . . . . . 154
A.4 Networking with Apache. . . . . . . . . . . . . . 157
A.5 Securing Subversion . . . . . . . . . . . . . . . . 163
A.6 Backing Up Your Repository . . . . . . . . . . . 170
B Migrating to Subversion 174
B.1 Getting cvs2svn. . . . . . . . . . . . . . . . . . . 175
B.2 Choosing How Much to Convert . . . . . . . . . 175
B.3 Converting Your Repository . . . . . . . . . . . . 176
C Third-Party Subversion Tools 178
C.1 TortoiseSVN . . . . . . . . . . . . . . . . . . . . . 178
C.2 IDE Integration . . . . . . . . . . . . . . . . . . . 185
C.3 Other Tools . . . . . . . . . . . . . . . . . . . . . 186
D Advanced Topics 188
D.1 Programmatic Access to Subversion . . . . . . . 188
D.2 Advanced Repository Management . . . . . . . 193
E Command Summary and Recipes 197
E.1 Subversion Command Summary . . . . . . . . . 197
E.2 Recipes . . . . . . . . . . . . . . . . . . . . . . . 208
F Other Resources 214
F.1 Online Resources . . . . . . . . . . . . . . . . . . 214
F.2 Bibliography . . . . . . . . . . . . . . . . . . . . 215
Preface
Iwasprettyexcited whenIheardabout thePragmaticStarter
Kit—finallysome guidance on thebasicstuff all projectsneed
to get right. The opportunity to produce a Subversion edition
of Pragmatic Version Control was one I couldn’t miss. Sub-
version had previously saved me (and my team) from version
control hell, and I wanted to do my part to help promote a
great new version control system.
Versioncontroladdsanimmenseamounttoaproject. Itgives
you a safety net, helps your team collaborate effectively, lets
you organize your builds and QA, and even allows you to do
somedetectiveworkifthingsgowrong. Ihopethisnewedition
of Pragmatic Version Control will help you and your team get
started and succeed with Subversion.
Acknowledgments
I’d like to thank Dave and Andy for taking a chance on my
writingthebookandtothankDaveforbeingsuchanexcellent
editor. Iwasn’t reallysure whatIwas gettingmyselfinto, and
Dave’s advice and guidance were invaluable.
The book received plenty of scrutiny by reviewers; I’d like to
thank Brad Appleton, Branko Cˇibej, Martin Fowler, Steffen
Gemkow, Robert Rasmussen, Mike Roberts, and David Rupp
for their well-thought-out comments and suggestions. I’m
franklyamazedbythequalityoffeedbackIgot—greatsugges-
tions, highly technical comments and plenty of people think-
ing about the “bigger picture.”
Everyone at ThoughtWorks has been really supportive of my
book writing efforts, including several people who took the
time to look through early drafts of the book, and I’d like to
PREFACE ix
thankallthosewhogavemeadviceandguidance. I’dparticu-
larlyliketothanktheCalgaryofficeforwelcomingmeintothe
fold this year and for enabling me to get stuff finished when
the crunch point came.
FinallyI’dliketothankMartin,Mike,andMichelleformaking
me believe I could really write the book and for their encour-
agement along the way.
December2004
Acknowledgments for the Second Edition
Subversion has come a long way since the first edition of this
book. Ithasnewfeatures,performanceandstabilityimprove-
ments, and most importantly has excellent integration with
many leading tools and IDEs. Subversion is now probably
the number one version control tool in use on ThoughtWorks
projects and is a serious competitor to every commercial tool
on the market.
I’dliketothankeveryonewhohasgivenmesupport andfeed-
back since the publication of the original book. It’s very grat-
ifying to know people have used the book, enjoyed reading it,
and that Subversion has brought them success. Please keep
the feedback coming, it’s invaluable.
The following people generously contributed time reading the
updated manuscript, and provided fantastic feedback: Steve
Berczuk, Nick Coyne, David Rupp and Nate Schutta. Thank
you all for your time, effort, and great ideas.
I’d like to thank Dave and Andy for the opportunity to update
the book to cover new features in Subversion, and in partic-
ular I’d like to thank Andy for taking on the editor’s job this
timearound. As I’ve told many friendsand colleagues, agood
editor is a crucial part of the writing process, and I feel very
lucky to have worked with both Andy and Dave.
Mike Mason
May2006
[email protected]
PREFACE x
Typographic Conventions
italic font Italics indicate a term that is being defined, or
borrowed fromanother language.
files Files (and directories) are indicated like this.
commands Commands (and options such as -h) are shown
like this.
output Output (aswellasthingsyoumightneedtotype)
is indicated like this. If commands are too long
for a single line they’re split onto multiple lines
using a \ (backward slash).
CVSHint: This kind of text indicates a hint for users famil-
iar with CVS.
This warningsign indicatesthismaterial ismore
advanced and can be skipped on your first read-
ing.
“Joe the developer,” our cartoon friend, asks a
related question that you may find useful.
