hgbook
diff en/ch00-preface.xml @ 704:acf9dc5f088d
Add a skeletal preface.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu May 07 21:07:35 2009 -0700 (2009-05-07) |
| parents | b338f5490029 |
| children | d5688822c51d |
line diff
1.1 --- a/en/ch00-preface.xml Thu Apr 09 22:52:16 2009 -0700 1.2 +++ b/en/ch00-preface.xml Thu May 07 21:07:35 2009 -0700 1.3 @@ -5,751 +5,153 @@ 1.4 <title>Preface</title> 1.5 1.6 <sect1> 1.7 - <title>Why revision control? Why Mercurial?</title> 1.8 + <title>Conventions Used in This Book</title> 1.9 1.10 - <para id="x_6d">Revision control is the process of managing multiple 1.11 - versions of a piece of information. In its simplest form, this 1.12 - is something that many people do by hand: every time you modify 1.13 - a file, save it under a new name that contains a number, each 1.14 - one higher than the number of the preceding version.</para> 1.15 + <para>The following typographical conventions are used in this 1.16 + book:</para> 1.17 1.18 - <para id="x_6e">Manually managing multiple versions of even a single file is 1.19 - an error-prone task, though, so software tools to help automate 1.20 - this process have long been available. The earliest automated 1.21 - revision control tools were intended to help a single user to 1.22 - manage revisions of a single file. Over the past few decades, 1.23 - the scope of revision control tools has expanded greatly; they 1.24 - now manage multiple files, and help multiple people to work 1.25 - together. The best modern revision control tools have no 1.26 - problem coping with thousands of people working together on 1.27 - projects that consist of hundreds of thousands of files.</para> 1.28 + <variablelist> 1.29 + <varlistentry> 1.30 + <term>Italic</term> 1.31 1.32 - <para id="x_6f">The arrival of distributed revision control is relatively 1.33 - recent, and so far this new field has grown due to people's 1.34 - willingness to explore ill-charted territory.</para> 1.35 + <listitem> 1.36 + <para>Indicates new terms, URLs, email addresses, filenames, 1.37 + and file extensions.</para> 1.38 + </listitem> 1.39 + </varlistentry> 1.40 1.41 - <para id="x_70">I am writing a book about distributed revision control 1.42 - because I believe that it is an important subject that deserves 1.43 - a field guide. I chose to write about Mercurial because it is 1.44 - the easiest tool to learn the terrain with, and yet it scales to 1.45 - the demands of real, challenging environments where many other 1.46 - revision control tools buckle.</para> 1.47 + <varlistentry> 1.48 + <term><literal>Constant width</literal></term> 1.49 1.50 - <sect2> 1.51 - <title>Why use revision control?</title> 1.52 + <listitem> 1.53 + <para>Used for program listings, as well as within 1.54 + paragraphs to refer to program elements such as variable 1.55 + or function names, databases, data types, environment 1.56 + variables, statements, and keywords.</para> 1.57 + </listitem> 1.58 + </varlistentry> 1.59 1.60 - <para id="x_71">There are a number of reasons why you or your team might 1.61 - want to use an automated revision control tool for a 1.62 - project.</para> 1.63 + <varlistentry> 1.64 + <term><userinput>Constant width bold</userinput></term> 1.65 1.66 - <itemizedlist> 1.67 - <listitem><para id="x_72">It will track the history and evolution of 1.68 - your project, so you don't have to. For every change, 1.69 - you'll have a log of <emphasis>who</emphasis> made it; 1.70 - <emphasis>why</emphasis> they made it; 1.71 - <emphasis>when</emphasis> they made it; and 1.72 - <emphasis>what</emphasis> the change 1.73 - was.</para></listitem> 1.74 - <listitem><para id="x_73">When you're working with other people, 1.75 - revision control software makes it easier for you to 1.76 - collaborate. For example, when people more or less 1.77 - simultaneously make potentially incompatible changes, the 1.78 - software will help you to identify and resolve those 1.79 - conflicts.</para></listitem> 1.80 - <listitem><para id="x_74">It can help you to recover from mistakes. If 1.81 - you make a change that later turns out to be in error, you 1.82 - can revert to an earlier version of one or more files. In 1.83 - fact, a <emphasis>really</emphasis> good revision control 1.84 - tool will even help you to efficiently figure out exactly 1.85 - when a problem was introduced (see <xref 1.86 - linkend="sec:undo:bisect"/> for details).</para></listitem> 1.87 - <listitem><para id="x_75">It will help you to work simultaneously on, 1.88 - and manage the drift between, multiple versions of your 1.89 - project.</para></listitem> 1.90 - </itemizedlist> 1.91 + <listitem> 1.92 + <para>Shows commands or other text that should be typed 1.93 + literally by the user.</para> 1.94 + </listitem> 1.95 + </varlistentry> 1.96 1.97 - <para id="x_76">Most of these reasons are equally 1.98 - valid&emdash;at least in theory&emdash;whether you're working 1.99 - on a project by yourself, or with a hundred other 1.100 - people.</para> 1.101 + <varlistentry> 1.102 + <term><replaceable>Constant width italic</replaceable></term> 1.103 1.104 - <para id="x_77">A key question about the practicality of revision control 1.105 - at these two different scales (<quote>lone hacker</quote> and 1.106 - <quote>huge team</quote>) is how its 1.107 - <emphasis>benefits</emphasis> compare to its 1.108 - <emphasis>costs</emphasis>. A revision control tool that's 1.109 - difficult to understand or use is going to impose a high 1.110 - cost.</para> 1.111 + <listitem> 1.112 + <para>Shows text that should be replaced with user-supplied 1.113 + values or by values determined by context.</para> 1.114 + </listitem> 1.115 + </varlistentry> 1.116 + </variablelist> 1.117 1.118 - <para id="x_78">A five-hundred-person project is likely to collapse under 1.119 - its own weight almost immediately without a revision control 1.120 - tool and process. In this case, the cost of using revision 1.121 - control might hardly seem worth considering, since 1.122 - <emphasis>without</emphasis> it, failure is almost 1.123 - guaranteed.</para> 1.124 + <tip> 1.125 + <para>This icon signifies a tip, suggestion, or general 1.126 + note.</para> 1.127 + </tip> 1.128 1.129 - <para id="x_79">On the other hand, a one-person <quote>quick hack</quote> 1.130 - might seem like a poor place to use a revision control tool, 1.131 - because surely the cost of using one must be close to the 1.132 - overall cost of the project. Right?</para> 1.133 - 1.134 - <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of 1.135 - these scales of development. You can learn the basics in just 1.136 - a few minutes, and due to its low overhead, you can apply 1.137 - revision control to the smallest of projects with ease. Its 1.138 - simplicity means you won't have a lot of abstruse concepts or 1.139 - command sequences competing for mental space with whatever 1.140 - you're <emphasis>really</emphasis> trying to do. At the same 1.141 - time, Mercurial's high performance and peer-to-peer nature let 1.142 - you scale painlessly to handle large projects.</para> 1.143 - 1.144 - <para id="x_7b">No revision control tool can rescue a poorly run project, 1.145 - but a good choice of tools can make a huge difference to the 1.146 - fluidity with which you can work on a project.</para> 1.147 - 1.148 - </sect2> 1.149 - 1.150 - <sect2> 1.151 - <title>The many names of revision control</title> 1.152 - 1.153 - <para id="x_7c">Revision control is a diverse field, so much so that it is 1.154 - referred to by many names and acronyms. Here are a few of the 1.155 - more common variations you'll encounter:</para> 1.156 - <itemizedlist> 1.157 - <listitem><para id="x_7d">Revision control (RCS)</para></listitem> 1.158 - <listitem><para id="x_7e">Software configuration management (SCM), or 1.159 - configuration management</para></listitem> 1.160 - <listitem><para id="x_7f">Source code management</para></listitem> 1.161 - <listitem><para id="x_80">Source code control, or source 1.162 - control</para></listitem> 1.163 - <listitem><para id="x_81">Version control 1.164 - (VCS)</para></listitem></itemizedlist> 1.165 - <para id="x_82">Some people claim that these terms actually have different 1.166 - meanings, but in practice they overlap so much that there's no 1.167 - agreed or even useful way to tease them apart.</para> 1.168 - 1.169 - </sect2> 1.170 + <caution> 1.171 + <para>This icon indicates a warning or caution.</para> 1.172 + </caution> 1.173 </sect1> 1.174 1.175 <sect1> 1.176 - <title>This book is a work in progress</title> 1.177 + <title>Using Code Examples</title> 1.178 1.179 - <para id="x_83">I am releasing this book while I am still writing it, in the 1.180 - hope that it will prove useful to others. I am writing under an 1.181 - open license in the hope that you, my readers, will contribute 1.182 - feedback and perhaps content of your own.</para> 1.183 + <para>This book is here to help you get your job done. In general, 1.184 + you may use the code in this book in your programs and 1.185 + documentation. You do not need to contact us for permission 1.186 + unless you’re reproducing a significant portion of the code. For 1.187 + example, writing a program that uses several chunks of code from 1.188 + this book does not require permission. Selling or distributing a 1.189 + CD-ROM of examples from O’Reilly books does require permission. 1.190 + Answering a question by citing this book and quoting example 1.191 + code does not require permission. Incorporating a significant 1.192 + amount of example code from this book into your product’s 1.193 + documentation does require permission.</para> 1.194 1.195 - </sect1> 1.196 - <sect1> 1.197 - <title>About the examples in this book</title> 1.198 + <para>We appreciate, but do not require, attribution. An 1.199 + attribution usually includes the title, author, publisher, and 1.200 + ISBN. For example: “<emphasis>Book Title</emphasis> by Some 1.201 + Author. Copyright 2008 O’Reilly Media, Inc., 1.202 + 978-0-596-xxxx-x.”</para> 1.203 1.204 - <para id="x_84">This book takes an unusual approach to code samples. Every 1.205 - example is <quote>live</quote>&emdash;each one is actually the result 1.206 - of a shell script that executes the Mercurial commands you see. 1.207 - Every time an image of the book is built from its sources, all 1.208 - the example scripts are automatically run, and their current 1.209 - results compared against their expected results.</para> 1.210 - 1.211 - <para id="x_85">The advantage of this approach is that the examples are 1.212 - always accurate; they describe <emphasis>exactly</emphasis> the 1.213 - behavior of the version of Mercurial that's mentioned at the 1.214 - front of the book. If I update the version of Mercurial that 1.215 - I'm documenting, and the output of some command changes, the 1.216 - build fails.</para> 1.217 - 1.218 - <para id="x_86">There is a small disadvantage to this approach, which is 1.219 - that the dates and times you'll see in examples tend to be 1.220 - <quote>squashed</quote> together in a way that they wouldn't be 1.221 - if the same commands were being typed by a human. Where a human 1.222 - can issue no more than one command every few seconds, with any 1.223 - resulting timestamps correspondingly spread out, my automated 1.224 - example scripts run many commands in one second.</para> 1.225 - 1.226 - <para id="x_87">As an instance of this, several consecutive commits in an 1.227 - example can show up as having occurred during the same second. 1.228 - You can see this occur in the <literal 1.229 - role="hg-ext">bisect</literal> example in <xref 1.230 - linkend="sec:undo:bisect"/>, for instance.</para> 1.231 - 1.232 - <para id="x_88">So when you're reading examples, don't place too much weight 1.233 - on the dates or times you see in the output of commands. But 1.234 - <emphasis>do</emphasis> be confident that the behavior you're 1.235 - seeing is consistent and reproducible.</para> 1.236 - 1.237 + <para>If you feel your use of code examples falls outside fair use 1.238 + or the permission given above, feel free to contact us at 1.239 + <email>permissions@oreilly.com</email>.</para> 1.240 </sect1> 1.241 1.242 <sect1> 1.243 - <title>Trends in the field</title> 1.244 + <title>Safari® Books Online</title> 1.245 1.246 - <para id="x_89">There has been an unmistakable trend in the development and 1.247 - use of revision control tools over the past four decades, as 1.248 - people have become familiar with the capabilities of their tools 1.249 - and constrained by their limitations.</para> 1.250 + <note role="safarienabled"> 1.251 + <para>When you see a Safari® Books Online icon on the cover of 1.252 + your favorite technology book, that means the book is 1.253 + available online through the O’Reilly Network Safari 1.254 + Bookshelf.</para> 1.255 + </note> 1.256 1.257 - <para id="x_8a">The first generation began by managing single files on 1.258 - individual computers. Although these tools represented a huge 1.259 - advance over ad-hoc manual revision control, their locking model 1.260 - and reliance on a single computer limited them to small, 1.261 - tightly-knit teams.</para> 1.262 - 1.263 - <para id="x_8b">The second generation loosened these constraints by moving 1.264 - to network-centered architectures, and managing entire projects 1.265 - at a time. As projects grew larger, they ran into new problems. 1.266 - With clients needing to talk to servers very frequently, server 1.267 - scaling became an issue for large projects. An unreliable 1.268 - network connection could prevent remote users from being able to 1.269 - talk to the server at all. As open source projects started 1.270 - making read-only access available anonymously to anyone, people 1.271 - without commit privileges found that they could not use the 1.272 - tools to interact with a project in a natural way, as they could 1.273 - not record their changes.</para> 1.274 - 1.275 - <para id="x_8c">The current generation of revision control tools is 1.276 - peer-to-peer in nature. All of these systems have dropped the 1.277 - dependency on a single central server, and allow people to 1.278 - distribute their revision control data to where it's actually 1.279 - needed. Collaboration over the Internet has moved from 1.280 - constrained by technology to a matter of choice and consensus. 1.281 - Modern tools can operate offline indefinitely and autonomously, 1.282 - with a network connection only needed when syncing changes with 1.283 - another repository.</para> 1.284 - 1.285 - </sect1> 1.286 - <sect1> 1.287 - <title>A few of the advantages of distributed revision 1.288 - control</title> 1.289 - 1.290 - <para id="x_8d">Even though distributed revision control tools have for 1.291 - several years been as robust and usable as their 1.292 - previous-generation counterparts, people using older tools have 1.293 - not yet necessarily woken up to their advantages. There are a 1.294 - number of ways in which distributed tools shine relative to 1.295 - centralised ones.</para> 1.296 - 1.297 - <para id="x_8e">For an individual developer, distributed tools are almost 1.298 - always much faster than centralised tools. This is for a simple 1.299 - reason: a centralised tool needs to talk over the network for 1.300 - many common operations, because most metadata is stored in a 1.301 - single copy on the central server. A distributed tool stores 1.302 - all of its metadata locally. All else being equal, talking over 1.303 - the network adds overhead to a centralised tool. Don't 1.304 - underestimate the value of a snappy, responsive tool: you're 1.305 - going to spend a lot of time interacting with your revision 1.306 - control software.</para> 1.307 - 1.308 - <para id="x_8f">Distributed tools are indifferent to the vagaries of your 1.309 - server infrastructure, again because they replicate metadata to 1.310 - so many locations. If you use a centralised system and your 1.311 - server catches fire, you'd better hope that your backup media 1.312 - are reliable, and that your last backup was recent and actually 1.313 - worked. With a distributed tool, you have many backups 1.314 - available on every contributor's computer.</para> 1.315 - 1.316 - <para id="x_90">The reliability of your network will affect distributed 1.317 - tools far less than it will centralised tools. You can't even 1.318 - use a centralised tool without a network connection, except for 1.319 - a few highly constrained commands. With a distributed tool, if 1.320 - your network connection goes down while you're working, you may 1.321 - not even notice. The only thing you won't be able to do is talk 1.322 - to repositories on other computers, something that is relatively 1.323 - rare compared with local operations. If you have a far-flung 1.324 - team of collaborators, this may be significant.</para> 1.325 - 1.326 - <sect2> 1.327 - <title>Advantages for open source projects</title> 1.328 - 1.329 - <para id="x_91">If you take a shine to an open source project and decide 1.330 - that you would like to start hacking on it, and that project 1.331 - uses a distributed revision control tool, you are at once a 1.332 - peer with the people who consider themselves the 1.333 - <quote>core</quote> of that project. If they publish their 1.334 - repositories, you can immediately copy their project history, 1.335 - start making changes, and record your work, using the same 1.336 - tools in the same ways as insiders. By contrast, with a 1.337 - centralised tool, you must use the software in a <quote>read 1.338 - only</quote> mode unless someone grants you permission to 1.339 - commit changes to their central server. Until then, you won't 1.340 - be able to record changes, and your local modifications will 1.341 - be at risk of corruption any time you try to update your 1.342 - client's view of the repository.</para> 1.343 - 1.344 - <sect3> 1.345 - <title>The forking non-problem</title> 1.346 - 1.347 - <para id="x_92">It has been suggested that distributed revision control 1.348 - tools pose some sort of risk to open source projects because 1.349 - they make it easy to <quote>fork</quote> the development of 1.350 - a project. A fork happens when there are differences in 1.351 - opinion or attitude between groups of developers that cause 1.352 - them to decide that they can't work together any longer. 1.353 - Each side takes a more or less complete copy of the 1.354 - project's source code, and goes off in its own 1.355 - direction.</para> 1.356 - 1.357 - <para id="x_93">Sometimes the camps in a fork decide to reconcile their 1.358 - differences. With a centralised revision control system, the 1.359 - <emphasis>technical</emphasis> process of reconciliation is 1.360 - painful, and has to be performed largely by hand. You have 1.361 - to decide whose revision history is going to 1.362 - <quote>win</quote>, and graft the other team's changes into 1.363 - the tree somehow. This usually loses some or all of one 1.364 - side's revision history.</para> 1.365 - 1.366 - <para id="x_94">What distributed tools do with respect to forking is 1.367 - they make forking the <emphasis>only</emphasis> way to 1.368 - develop a project. Every single change that you make is 1.369 - potentially a fork point. The great strength of this 1.370 - approach is that a distributed revision control tool has to 1.371 - be really good at <emphasis>merging</emphasis> forks, 1.372 - because forks are absolutely fundamental: they happen all 1.373 - the time.</para> 1.374 - 1.375 - <para id="x_95">If every piece of work that everybody does, all the 1.376 - time, is framed in terms of forking and merging, then what 1.377 - the open source world refers to as a <quote>fork</quote> 1.378 - becomes <emphasis>purely</emphasis> a social issue. If 1.379 - anything, distributed tools <emphasis>lower</emphasis> the 1.380 - likelihood of a fork:</para> 1.381 - <itemizedlist> 1.382 - <listitem><para id="x_96">They eliminate the social distinction that 1.383 - centralised tools impose: that between insiders (people 1.384 - with commit access) and outsiders (people 1.385 - without).</para></listitem> 1.386 - <listitem><para id="x_97">They make it easier to reconcile after a 1.387 - social fork, because all that's involved from the 1.388 - perspective of the revision control software is just 1.389 - another merge.</para></listitem></itemizedlist> 1.390 - 1.391 - <para id="x_98">Some people resist distributed tools because they want 1.392 - to retain tight control over their projects, and they 1.393 - believe that centralised tools give them this control. 1.394 - However, if you're of this belief, and you publish your CVS 1.395 - or Subversion repositories publicly, there are plenty of 1.396 - tools available that can pull out your entire project's 1.397 - history (albeit slowly) and recreate it somewhere that you 1.398 - don't control. So while your control in this case is 1.399 - illusory, you are forgoing the ability to fluidly 1.400 - collaborate with whatever people feel compelled to mirror 1.401 - and fork your history.</para> 1.402 - 1.403 - </sect3> 1.404 - </sect2> 1.405 - <sect2> 1.406 - <title>Advantages for commercial projects</title> 1.407 - 1.408 - <para id="x_99">Many commercial projects are undertaken by teams that are 1.409 - scattered across the globe. Contributors who are far from a 1.410 - central server will see slower command execution and perhaps 1.411 - less reliability. Commercial revision control systems attempt 1.412 - to ameliorate these problems with remote-site replication 1.413 - add-ons that are typically expensive to buy and cantankerous 1.414 - to administer. A distributed system doesn't suffer from these 1.415 - problems in the first place. Better yet, you can easily set 1.416 - up multiple authoritative servers, say one per site, so that 1.417 - there's no redundant communication between repositories over 1.418 - expensive long-haul network links.</para> 1.419 - 1.420 - <para id="x_9a">Centralised revision control systems tend to have 1.421 - relatively low scalability. It's not unusual for an expensive 1.422 - centralised system to fall over under the combined load of 1.423 - just a few dozen concurrent users. Once again, the typical 1.424 - response tends to be an expensive and clunky replication 1.425 - facility. Since the load on a central server&emdash;if you have 1.426 - one at all&emdash;is many times lower with a distributed tool 1.427 - (because all of the data is replicated everywhere), a single 1.428 - cheap server can handle the needs of a much larger team, and 1.429 - replication to balance load becomes a simple matter of 1.430 - scripting.</para> 1.431 - 1.432 - <para id="x_9b">If you have an employee in the field, troubleshooting a 1.433 - problem at a customer's site, they'll benefit from distributed 1.434 - revision control. The tool will let them generate custom 1.435 - builds, try different fixes in isolation from each other, and 1.436 - search efficiently through history for the sources of bugs and 1.437 - regressions in the customer's environment, all without needing 1.438 - to connect to your company's network.</para> 1.439 - 1.440 - </sect2> 1.441 - </sect1> 1.442 - <sect1> 1.443 - <title>Why choose Mercurial?</title> 1.444 - 1.445 - <para id="x_9c">Mercurial has a unique set of properties that make it a 1.446 - particularly good choice as a revision control system.</para> 1.447 - <itemizedlist> 1.448 - <listitem><para id="x_9d">It is easy to learn and use.</para></listitem> 1.449 - <listitem><para id="x_9e">It is lightweight.</para></listitem> 1.450 - <listitem><para id="x_9f">It scales excellently.</para></listitem> 1.451 - <listitem><para id="x_a0">It is easy to 1.452 - customise.</para></listitem></itemizedlist> 1.453 - 1.454 - <para id="x_a1">If you are at all familiar with revision control systems, 1.455 - you should be able to get up and running with Mercurial in less 1.456 - than five minutes. Even if not, it will take no more than a few 1.457 - minutes longer. Mercurial's command and feature sets are 1.458 - generally uniform and consistent, so you can keep track of a few 1.459 - general rules instead of a host of exceptions.</para> 1.460 - 1.461 - <para id="x_a2">On a small project, you can start working with Mercurial in 1.462 - moments. Creating new changes and branches; transferring changes 1.463 - around (whether locally or over a network); and history and 1.464 - status operations are all fast. Mercurial attempts to stay 1.465 - nimble and largely out of your way by combining low cognitive 1.466 - overhead with blazingly fast operations.</para> 1.467 - 1.468 - <para id="x_a3">The usefulness of Mercurial is not limited to small 1.469 - projects: it is used by projects with hundreds to thousands of 1.470 - contributors, each containing tens of thousands of files and 1.471 - hundreds of megabytes of source code.</para> 1.472 - 1.473 - <para id="x_a4">If the core functionality of Mercurial is not enough for 1.474 - you, it's easy to build on. Mercurial is well suited to 1.475 - scripting tasks, and its clean internals and implementation in 1.476 - Python make it easy to add features in the form of extensions. 1.477 - There are a number of popular and useful extensions already 1.478 - available, ranging from helping to identify bugs to improving 1.479 - performance.</para> 1.480 - 1.481 - </sect1> 1.482 - <sect1> 1.483 - <title>Mercurial compared with other tools</title> 1.484 - 1.485 - <para id="x_a5">Before you read on, please understand that this section 1.486 - necessarily reflects my own experiences, interests, and (dare I 1.487 - say it) biases. I have used every one of the revision control 1.488 - tools listed below, in most cases for several years at a 1.489 - time.</para> 1.490 - 1.491 - 1.492 - <sect2> 1.493 - <title>Subversion</title> 1.494 - 1.495 - <para id="x_a6">Subversion is a popular revision control tool, developed 1.496 - to replace CVS. It has a centralised client/server 1.497 - architecture.</para> 1.498 - 1.499 - <para id="x_a7">Subversion and Mercurial have similarly named commands for 1.500 - performing the same operations, so if you're familiar with 1.501 - one, it is easy to learn to use the other. Both tools are 1.502 - portable to all popular operating systems.</para> 1.503 - 1.504 - <para id="x_a8">Prior to version 1.5, Subversion had no useful support for 1.505 - merges. At the time of writing, its merge tracking capability 1.506 - is new, and known to be <ulink 1.507 - url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 1.508 - and buggy</ulink>.</para> 1.509 - 1.510 - <para id="x_a9">Mercurial has a substantial performance advantage over 1.511 - Subversion on every revision control operation I have 1.512 - benchmarked. I have measured its advantage as ranging from a 1.513 - factor of two to a factor of six when compared with Subversion 1.514 - 1.4.3's <emphasis>ra_local</emphasis> file store, which is the 1.515 - fastest access method available. In more realistic 1.516 - deployments involving a network-based store, Subversion will 1.517 - be at a substantially larger disadvantage. Because many 1.518 - Subversion commands must talk to the server and Subversion 1.519 - does not have useful replication facilities, server capacity 1.520 - and network bandwidth become bottlenecks for modestly large 1.521 - projects.</para> 1.522 - 1.523 - <para id="x_aa">Additionally, Subversion incurs substantial storage 1.524 - overhead to avoid network transactions for a few common 1.525 - operations, such as finding modified files 1.526 - (<literal>status</literal>) and displaying modifications 1.527 - against the current revision (<literal>diff</literal>). As a 1.528 - result, a Subversion working copy is often the same size as, 1.529 - or larger than, a Mercurial repository and working directory, 1.530 - even though the Mercurial repository contains a complete 1.531 - history of the project.</para> 1.532 - 1.533 - <para id="x_ab">Subversion is widely supported by third party tools. 1.534 - Mercurial currently lags considerably in this area. This gap 1.535 - is closing, however, and indeed some of Mercurial's GUI tools 1.536 - now outshine their Subversion equivalents. Like Mercurial, 1.537 - Subversion has an excellent user manual.</para> 1.538 - 1.539 - <para id="x_ac">Because Subversion doesn't store revision history on the 1.540 - client, it is well suited to managing projects that deal with 1.541 - lots of large, opaque binary files. If you check in fifty 1.542 - revisions to an incompressible 10MB file, Subversion's 1.543 - client-side space usage stays constant The space used by any 1.544 - distributed SCM will grow rapidly in proportion to the number 1.545 - of revisions, because the differences between each revision 1.546 - are large.</para> 1.547 - 1.548 - <para id="x_ad">In addition, it's often difficult or, more usually, 1.549 - impossible to merge different versions of a binary file. 1.550 - Subversion's ability to let a user lock a file, so that they 1.551 - temporarily have the exclusive right to commit changes to it, 1.552 - can be a significant advantage to a project where binary files 1.553 - are widely used.</para> 1.554 - 1.555 - <para id="x_ae">Mercurial can import revision history from a Subversion 1.556 - repository. It can also export revision history to a 1.557 - Subversion repository. This makes it easy to <quote>test the 1.558 - waters</quote> and use Mercurial and Subversion in parallel 1.559 - before deciding to switch. History conversion is incremental, 1.560 - so you can perform an initial conversion, then small 1.561 - additional conversions afterwards to bring in new 1.562 - changes.</para> 1.563 - 1.564 - 1.565 - </sect2> 1.566 - <sect2> 1.567 - <title>Git</title> 1.568 - 1.569 - <para id="x_af">Git is a distributed revision control tool that was 1.570 - developed for managing the Linux kernel source tree. Like 1.571 - Mercurial, its early design was somewhat influenced by 1.572 - Monotone.</para> 1.573 - 1.574 - <para id="x_b0">Git has a very large command set, with version 1.5.0 1.575 - providing 139 individual commands. It has something of a 1.576 - reputation for being difficult to learn. Compared to Git, 1.577 - Mercurial has a strong focus on simplicity.</para> 1.578 - 1.579 - <para id="x_b1">In terms of performance, Git is extremely fast. In 1.580 - several cases, it is faster than Mercurial, at least on Linux, 1.581 - while Mercurial performs better on other operations. However, 1.582 - on Windows, the performance and general level of support that 1.583 - Git provides is, at the time of writing, far behind that of 1.584 - Mercurial.</para> 1.585 - 1.586 - <para id="x_b2">While a Mercurial repository needs no maintenance, a Git 1.587 - repository requires frequent manual <quote>repacks</quote> of 1.588 - its metadata. Without these, performance degrades, while 1.589 - space usage grows rapidly. A server that contains many Git 1.590 - repositories that are not rigorously and frequently repacked 1.591 - will become heavily disk-bound during backups, and there have 1.592 - been instances of daily backups taking far longer than 24 1.593 - hours as a result. A freshly packed Git repository is 1.594 - slightly smaller than a Mercurial repository, but an unpacked 1.595 - repository is several orders of magnitude larger.</para> 1.596 - 1.597 - <para id="x_b3">The core of Git is written in C. Many Git commands are 1.598 - implemented as shell or Perl scripts, and the quality of these 1.599 - scripts varies widely. I have encountered several instances 1.600 - where scripts charged along blindly in the presence of errors 1.601 - that should have been fatal.</para> 1.602 - 1.603 - <para id="x_b4">Mercurial can import revision history from a Git 1.604 - repository.</para> 1.605 - 1.606 - 1.607 - </sect2> 1.608 - <sect2> 1.609 - <title>CVS</title> 1.610 - 1.611 - <para id="x_b5">CVS is probably the most widely used revision control tool 1.612 - in the world. Due to its age and internal untidiness, it has 1.613 - been only lightly maintained for many years.</para> 1.614 - 1.615 - <para id="x_b6">It has a centralised client/server architecture. It does 1.616 - not group related file changes into atomic commits, making it 1.617 - easy for people to <quote>break the build</quote>: one person 1.618 - can successfully commit part of a change and then be blocked 1.619 - by the need for a merge, causing other people to see only a 1.620 - portion of the work they intended to do. This also affects 1.621 - how you work with project history. If you want to see all of 1.622 - the modifications someone made as part of a task, you will 1.623 - need to manually inspect the descriptions and timestamps of 1.624 - the changes made to each file involved (if you even know what 1.625 - those files were).</para> 1.626 - 1.627 - <para id="x_b7">CVS has a muddled notion of tags and branches that I will 1.628 - not attempt to even describe. It does not support renaming of 1.629 - files or directories well, making it easy to corrupt a 1.630 - repository. It has almost no internal consistency checking 1.631 - capabilities, so it is usually not even possible to tell 1.632 - whether or how a repository is corrupt. I would not recommend 1.633 - CVS for any project, existing or new.</para> 1.634 - 1.635 - <para id="x_b8">Mercurial can import CVS revision history. However, there 1.636 - are a few caveats that apply; these are true of every other 1.637 - revision control tool's CVS importer, too. Due to CVS's lack 1.638 - of atomic changes and unversioned filesystem hierarchy, it is 1.639 - not possible to reconstruct CVS history completely accurately; 1.640 - some guesswork is involved, and renames will usually not show 1.641 - up. Because a lot of advanced CVS administration has to be 1.642 - done by hand and is hence error-prone, it's common for CVS 1.643 - importers to run into multiple problems with corrupted 1.644 - repositories (completely bogus revision timestamps and files 1.645 - that have remained locked for over a decade are just two of 1.646 - the less interesting problems I can recall from personal 1.647 - experience).</para> 1.648 - 1.649 - <para id="x_b9">Mercurial can import revision history from a CVS 1.650 - repository.</para> 1.651 - 1.652 - 1.653 - </sect2> 1.654 - <sect2> 1.655 - <title>Commercial tools</title> 1.656 - 1.657 - <para id="x_ba">Perforce has a centralised client/server architecture, 1.658 - with no client-side caching of any data. Unlike modern 1.659 - revision control tools, Perforce requires that a user run a 1.660 - command to inform the server about every file they intend to 1.661 - edit.</para> 1.662 - 1.663 - <para id="x_bb">The performance of Perforce is quite good for small teams, 1.664 - but it falls off rapidly as the number of users grows beyond a 1.665 - few dozen. Modestly large Perforce installations require the 1.666 - deployment of proxies to cope with the load their users 1.667 - generate.</para> 1.668 - 1.669 - 1.670 - </sect2> 1.671 - <sect2> 1.672 - <title>Choosing a revision control tool</title> 1.673 - 1.674 - <para id="x_bc">With the exception of CVS, all of the tools listed above 1.675 - have unique strengths that suit them to particular styles of 1.676 - work. There is no single revision control tool that is best 1.677 - in all situations.</para> 1.678 - 1.679 - <para id="x_bd">As an example, Subversion is a good choice for working 1.680 - with frequently edited binary files, due to its centralised 1.681 - nature and support for file locking.</para> 1.682 - 1.683 - <para id="x_be">I personally find Mercurial's properties of simplicity, 1.684 - performance, and good merge support to be a compelling 1.685 - combination that has served me well for several years.</para> 1.686 - 1.687 - 1.688 - </sect2> 1.689 - </sect1> 1.690 - <sect1> 1.691 - <title>Switching from another tool to Mercurial</title> 1.692 - 1.693 - <para id="x_bf">Mercurial is bundled with an extension named <literal 1.694 - role="hg-ext">convert</literal>, which can incrementally 1.695 - import revision history from several other revision control 1.696 - tools. By <quote>incremental</quote>, I mean that you can 1.697 - convert all of a project's history to date in one go, then rerun 1.698 - the conversion later to obtain new changes that happened after 1.699 - the initial conversion.</para> 1.700 - 1.701 - <para id="x_c0">The revision control tools supported by <literal 1.702 - role="hg-ext">convert</literal> are as follows:</para> 1.703 - <itemizedlist> 1.704 - <listitem><para id="x_c1">Subversion</para></listitem> 1.705 - <listitem><para id="x_c2">CVS</para></listitem> 1.706 - <listitem><para id="x_c3">Git</para></listitem> 1.707 - <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist> 1.708 - 1.709 - <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can 1.710 - export changes from Mercurial to Subversion. This makes it 1.711 - possible to try Subversion and Mercurial in parallel before 1.712 - committing to a switchover, without risking the loss of any 1.713 - work.</para> 1.714 - 1.715 - <para id="x_c6">The <command role="hg-ext-convert">convert</command> command 1.716 - is easy to use. Simply point it at the path or URL of the 1.717 - source repository, optionally give it the name of the 1.718 - destination repository, and it will start working. After the 1.719 - initial conversion, just run the same command again to import 1.720 - new changes.</para> 1.721 + <para>Safari offers a solution that’s better than e-books. It’s a 1.722 + virtual library that lets you easily search thousands of top 1.723 + tech books, cut and paste code samples, download chapters, and 1.724 + find quick answers when you need the most accurate, current 1.725 + information. Try it for free at <ulink role="orm:hideurl:ital" 1.726 + url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para> 1.727 </sect1> 1.728 1.729 <sect1> 1.730 - <title>A short history of revision control</title> 1.731 + <title>How to Contact Us</title> 1.732 1.733 - <para id="x_c7">The best known of the old-time revision control tools is 1.734 - SCCS (Source Code Control System), which Marc Rochkind wrote at 1.735 - Bell Labs, in the early 1970s. SCCS operated on individual 1.736 - files, and required every person working on a project to have 1.737 - access to a shared workspace on a single system. Only one 1.738 - person could modify a file at any time; arbitration for access 1.739 - to files was via locks. It was common for people to lock files, 1.740 - and later forget to unlock them, preventing anyone else from 1.741 - modifying those files without the help of an 1.742 - administrator.</para> 1.743 + <para>Please address comments and questions concerning this book 1.744 + to the publisher:</para> 1.745 1.746 - <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the 1.747 - early 1980s; he called his program RCS (Revision Control System). 1.748 - Like SCCS, RCS required developers to work in a single shared 1.749 - workspace, and to lock files to prevent multiple people from 1.750 - modifying them simultaneously.</para> 1.751 + <simplelist type="vert"> 1.752 + <member>O’Reilly Media, Inc.</member> 1.753 1.754 - <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block 1.755 - for a set of shell scripts he initially called cmt, but then 1.756 - renamed to CVS (Concurrent Versions System). The big innovation 1.757 - of CVS was that it let developers work simultaneously and 1.758 - somewhat independently in their own personal workspaces. The 1.759 - personal workspaces prevented developers from stepping on each 1.760 - other's toes all the time, as was common with SCCS and RCS. Each 1.761 - developer had a copy of every project file, and could modify 1.762 - their copies independently. They had to merge their edits prior 1.763 - to committing changes to the central repository.</para> 1.764 + <member>1005 Gravenstein Highway North</member> 1.765 1.766 - <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote 1.767 - them in C, releasing in 1989 the code that has since developed 1.768 - into the modern version of CVS. CVS subsequently acquired the 1.769 - ability to operate over a network connection, giving it a 1.770 - client/server architecture. CVS's architecture is centralised; 1.771 - only the server has a copy of the history of the project. Client 1.772 - workspaces just contain copies of recent versions of the 1.773 - project's files, and a little metadata to tell them where the 1.774 - server is. CVS has been enormously successful; it is probably 1.775 - the world's most widely used revision control system.</para> 1.776 + <member>Sebastopol, CA 95472</member> 1.777 1.778 - <para id="x_cb">In the early 1990s, Sun Microsystems developed an early 1.779 - distributed revision control system, called TeamWare. A 1.780 - TeamWare workspace contains a complete copy of the project's 1.781 - history. TeamWare has no notion of a central repository. (CVS 1.782 - relied upon RCS for its history storage; TeamWare used 1.783 - SCCS.)</para> 1.784 + <member>800-998-9938 (in the United States or Canada)</member> 1.785 1.786 - <para id="x_cc">As the 1990s progressed, awareness grew of a number of 1.787 - problems with CVS. It records simultaneous changes to multiple 1.788 - files individually, instead of grouping them together as a 1.789 - single logically atomic operation. It does not manage its file 1.790 - hierarchy well; it is easy to make a mess of a repository by 1.791 - renaming files and directories. Worse, its source code is 1.792 - difficult to read and maintain, which made the <quote>pain 1.793 - level</quote> of fixing these architectural problems 1.794 - prohibitive.</para> 1.795 + <member>707-829-0515 (international or local)</member> 1.796 1.797 - <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had 1.798 - worked on CVS, started a project to replace it with a tool that 1.799 - would have a better architecture and cleaner code. The result, 1.800 - Subversion, does not stray from CVS's centralised client/server 1.801 - model, but it adds multi-file atomic commits, better namespace 1.802 - management, and a number of other features that make it a 1.803 - generally better tool than CVS. Since its initial release, it 1.804 - has rapidly grown in popularity.</para> 1.805 + <member>707 829-0104 (fax)</member> 1.806 + </simplelist> 1.807 1.808 - <para id="x_ce">More or less simultaneously, Graydon Hoare began working on 1.809 - an ambitious distributed revision control system that he named 1.810 - Monotone. While Monotone addresses many of CVS's design flaws 1.811 - and has a peer-to-peer architecture, it goes beyond earlier (and 1.812 - subsequent) revision control tools in a number of innovative 1.813 - ways. It uses cryptographic hashes as identifiers, and has an 1.814 - integral notion of <quote>trust</quote> for code from different 1.815 - sources.</para> 1.816 + <para>We have a web page for this book, where we list errata, 1.817 + examples, and any additional information. You can access this 1.818 + page at:</para> 1.819 1.820 - <para id="x_cf">Mercurial began life in 2005. While a few aspects of its 1.821 - design are influenced by Monotone, Mercurial focuses on ease of 1.822 - use, high performance, and scalability to very large 1.823 - projects.</para> 1.824 + <simplelist type="vert"> 1.825 + <member><ulink url="http://www.oreilly.com/catalog/<catalog 1.826 + page>"></ulink></member> 1.827 + </simplelist> 1.828 1.829 - </sect1> 1.830 + <remark>Don’t forget to update the <url> attribute, 1.831 + too.</remark> 1.832 1.833 - <sect1> 1.834 - <title>Colophon&emdash;this book is Free</title> 1.835 + <para>To comment or ask technical questions about this book, send 1.836 + email to:</para> 1.837 1.838 - <para id="x_d0">This book is licensed under the Open Publication License, 1.839 - and is produced entirely using Free Software tools. It is 1.840 - typeset with DocBook XML. Illustrations are drawn and rendered with 1.841 - <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para> 1.842 + <simplelist type="vert"> 1.843 + <member><email>bookquestions@oreilly.com</email></member> 1.844 + </simplelist> 1.845 1.846 - <para id="x_d1">The complete source code for this book is published as a 1.847 - Mercurial repository, at <ulink 1.848 - url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para> 1.849 + <para>For more information about our books, conferences, Resource 1.850 + Centers, and the O’Reilly Network, see our web site at:</para> 1.851 1.852 + <simplelist type="vert"> 1.853 + <member><ulink url="http://www.oreilly.com"></ulink></member> 1.854 + </simplelist> 1.855 </sect1> 1.856 </preface> 1.857 + 1.858 <!-- 1.859 local variables: 1.860 sgml-parent-document: ("00book.xml" "book" "preface")