hgbook
changeset 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 | cbdff5945f9d |
children | d5688822c51d |
files | en/00book.xml en/ch00-preface.xml en/ch01-intro.xml en/ch01-tour-basic.xml en/ch02-tour-basic.xml en/ch02-tour-merge.xml en/ch03-concepts.xml en/ch03-tour-merge.xml en/ch04-concepts.xml en/ch04-daily.xml en/ch05-collab.xml en/ch05-daily.xml en/ch06-collab.xml en/ch06-filenames.xml en/ch07-branch.xml en/ch07-filenames.xml en/ch08-branch.xml en/ch08-undo.xml en/ch09-hook.xml en/ch09-undo.xml en/ch10-hook.xml en/ch10-template.xml en/ch11-mq.xml en/ch11-template.xml en/ch12-mq-collab.xml en/ch12-mq.xml en/ch13-hgext.xml en/ch13-mq-collab.xml en/ch14-hgext.xml |
line diff
1.1 --- a/en/00book.xml Thu May 07 21:06:49 2009 -0700 1.2 +++ b/en/00book.xml Thu May 07 21:07:35 2009 -0700 1.3 @@ -8,19 +8,20 @@ 1.4 <!-- Chapters. --> 1.5 1.6 <!ENTITY ch00 SYSTEM "ch00-preface.xml"> 1.7 -<!ENTITY ch01 SYSTEM "ch01-tour-basic.xml"> 1.8 -<!ENTITY ch02 SYSTEM "ch02-tour-merge.xml"> 1.9 -<!ENTITY ch03 SYSTEM "ch03-concepts.xml"> 1.10 -<!ENTITY ch04 SYSTEM "ch04-daily.xml"> 1.11 -<!ENTITY ch05 SYSTEM "ch05-collab.xml"> 1.12 -<!ENTITY ch06 SYSTEM "ch06-filenames.xml"> 1.13 -<!ENTITY ch07 SYSTEM "ch07-branch.xml"> 1.14 -<!ENTITY ch08 SYSTEM "ch08-undo.xml"> 1.15 -<!ENTITY ch09 SYSTEM "ch09-hook.xml"> 1.16 -<!ENTITY ch10 SYSTEM "ch10-template.xml"> 1.17 -<!ENTITY ch11 SYSTEM "ch11-mq.xml"> 1.18 -<!ENTITY ch12 SYSTEM "ch12-mq-collab.xml"> 1.19 -<!ENTITY ch13 SYSTEM "ch13-hgext.xml"> 1.20 +<!ENTITY ch01 SYSTEM "ch01-intro.xml"> 1.21 +<!ENTITY ch02 SYSTEM "ch02-tour-basic.xml"> 1.22 +<!ENTITY ch03 SYSTEM "ch03-tour-merge.xml"> 1.23 +<!ENTITY ch04 SYSTEM "ch04-concepts.xml"> 1.24 +<!ENTITY ch05 SYSTEM "ch05-daily.xml"> 1.25 +<!ENTITY ch06 SYSTEM "ch06-collab.xml"> 1.26 +<!ENTITY ch07 SYSTEM "ch07-filenames.xml"> 1.27 +<!ENTITY ch08 SYSTEM "ch08-branch.xml"> 1.28 +<!ENTITY ch09 SYSTEM "ch09-undo.xml"> 1.29 +<!ENTITY ch10 SYSTEM "ch10-hook.xml"> 1.30 +<!ENTITY ch11 SYSTEM "ch11-template.xml"> 1.31 +<!ENTITY ch12 SYSTEM "ch12-mq.xml"> 1.32 +<!ENTITY ch13 SYSTEM "ch13-mq-collab.xml"> 1.33 +<!ENTITY ch14 SYSTEM "ch14-hgext.xml"> 1.34 <!ENTITY appA SYSTEM "appA-svn.xml"> 1.35 <!ENTITY appB SYSTEM "appB-mq-ref.xml"> 1.36 <!ENTITY appC SYSTEM "appC-srcinstall.xml"> 1.37 @@ -96,6 +97,8 @@ 1.38 &ch12; 1.39 <!-- BEGIN ch13 --> 1.40 &ch13; 1.41 + <!-- BEGIN ch14 --> 1.42 + &ch14; 1.43 <!-- BEGIN appA --> 1.44 &appA; 1.45 <!-- BEGIN appB -->
2.1 --- a/en/ch00-preface.xml Thu May 07 21:06:49 2009 -0700 2.2 +++ b/en/ch00-preface.xml Thu May 07 21:07:35 2009 -0700 2.3 @@ -5,751 +5,153 @@ 2.4 <title>Preface</title> 2.5 2.6 <sect1> 2.7 - <title>Why revision control? Why Mercurial?</title> 2.8 + <title>Conventions Used in This Book</title> 2.9 2.10 - <para id="x_6d">Revision control is the process of managing multiple 2.11 - versions of a piece of information. In its simplest form, this 2.12 - is something that many people do by hand: every time you modify 2.13 - a file, save it under a new name that contains a number, each 2.14 - one higher than the number of the preceding version.</para> 2.15 + <para>The following typographical conventions are used in this 2.16 + book:</para> 2.17 2.18 - <para id="x_6e">Manually managing multiple versions of even a single file is 2.19 - an error-prone task, though, so software tools to help automate 2.20 - this process have long been available. The earliest automated 2.21 - revision control tools were intended to help a single user to 2.22 - manage revisions of a single file. Over the past few decades, 2.23 - the scope of revision control tools has expanded greatly; they 2.24 - now manage multiple files, and help multiple people to work 2.25 - together. The best modern revision control tools have no 2.26 - problem coping with thousands of people working together on 2.27 - projects that consist of hundreds of thousands of files.</para> 2.28 + <variablelist> 2.29 + <varlistentry> 2.30 + <term>Italic</term> 2.31 2.32 - <para id="x_6f">The arrival of distributed revision control is relatively 2.33 - recent, and so far this new field has grown due to people's 2.34 - willingness to explore ill-charted territory.</para> 2.35 + <listitem> 2.36 + <para>Indicates new terms, URLs, email addresses, filenames, 2.37 + and file extensions.</para> 2.38 + </listitem> 2.39 + </varlistentry> 2.40 2.41 - <para id="x_70">I am writing a book about distributed revision control 2.42 - because I believe that it is an important subject that deserves 2.43 - a field guide. I chose to write about Mercurial because it is 2.44 - the easiest tool to learn the terrain with, and yet it scales to 2.45 - the demands of real, challenging environments where many other 2.46 - revision control tools buckle.</para> 2.47 + <varlistentry> 2.48 + <term><literal>Constant width</literal></term> 2.49 2.50 - <sect2> 2.51 - <title>Why use revision control?</title> 2.52 + <listitem> 2.53 + <para>Used for program listings, as well as within 2.54 + paragraphs to refer to program elements such as variable 2.55 + or function names, databases, data types, environment 2.56 + variables, statements, and keywords.</para> 2.57 + </listitem> 2.58 + </varlistentry> 2.59 2.60 - <para id="x_71">There are a number of reasons why you or your team might 2.61 - want to use an automated revision control tool for a 2.62 - project.</para> 2.63 + <varlistentry> 2.64 + <term><userinput>Constant width bold</userinput></term> 2.65 2.66 - <itemizedlist> 2.67 - <listitem><para id="x_72">It will track the history and evolution of 2.68 - your project, so you don't have to. For every change, 2.69 - you'll have a log of <emphasis>who</emphasis> made it; 2.70 - <emphasis>why</emphasis> they made it; 2.71 - <emphasis>when</emphasis> they made it; and 2.72 - <emphasis>what</emphasis> the change 2.73 - was.</para></listitem> 2.74 - <listitem><para id="x_73">When you're working with other people, 2.75 - revision control software makes it easier for you to 2.76 - collaborate. For example, when people more or less 2.77 - simultaneously make potentially incompatible changes, the 2.78 - software will help you to identify and resolve those 2.79 - conflicts.</para></listitem> 2.80 - <listitem><para id="x_74">It can help you to recover from mistakes. If 2.81 - you make a change that later turns out to be in error, you 2.82 - can revert to an earlier version of one or more files. In 2.83 - fact, a <emphasis>really</emphasis> good revision control 2.84 - tool will even help you to efficiently figure out exactly 2.85 - when a problem was introduced (see <xref 2.86 - linkend="sec:undo:bisect"/> for details).</para></listitem> 2.87 - <listitem><para id="x_75">It will help you to work simultaneously on, 2.88 - and manage the drift between, multiple versions of your 2.89 - project.</para></listitem> 2.90 - </itemizedlist> 2.91 + <listitem> 2.92 + <para>Shows commands or other text that should be typed 2.93 + literally by the user.</para> 2.94 + </listitem> 2.95 + </varlistentry> 2.96 2.97 - <para id="x_76">Most of these reasons are equally 2.98 - valid&emdash;at least in theory&emdash;whether you're working 2.99 - on a project by yourself, or with a hundred other 2.100 - people.</para> 2.101 + <varlistentry> 2.102 + <term><replaceable>Constant width italic</replaceable></term> 2.103 2.104 - <para id="x_77">A key question about the practicality of revision control 2.105 - at these two different scales (<quote>lone hacker</quote> and 2.106 - <quote>huge team</quote>) is how its 2.107 - <emphasis>benefits</emphasis> compare to its 2.108 - <emphasis>costs</emphasis>. A revision control tool that's 2.109 - difficult to understand or use is going to impose a high 2.110 - cost.</para> 2.111 + <listitem> 2.112 + <para>Shows text that should be replaced with user-supplied 2.113 + values or by values determined by context.</para> 2.114 + </listitem> 2.115 + </varlistentry> 2.116 + </variablelist> 2.117 2.118 - <para id="x_78">A five-hundred-person project is likely to collapse under 2.119 - its own weight almost immediately without a revision control 2.120 - tool and process. In this case, the cost of using revision 2.121 - control might hardly seem worth considering, since 2.122 - <emphasis>without</emphasis> it, failure is almost 2.123 - guaranteed.</para> 2.124 + <tip> 2.125 + <para>This icon signifies a tip, suggestion, or general 2.126 + note.</para> 2.127 + </tip> 2.128 2.129 - <para id="x_79">On the other hand, a one-person <quote>quick hack</quote> 2.130 - might seem like a poor place to use a revision control tool, 2.131 - because surely the cost of using one must be close to the 2.132 - overall cost of the project. Right?</para> 2.133 - 2.134 - <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of 2.135 - these scales of development. You can learn the basics in just 2.136 - a few minutes, and due to its low overhead, you can apply 2.137 - revision control to the smallest of projects with ease. Its 2.138 - simplicity means you won't have a lot of abstruse concepts or 2.139 - command sequences competing for mental space with whatever 2.140 - you're <emphasis>really</emphasis> trying to do. At the same 2.141 - time, Mercurial's high performance and peer-to-peer nature let 2.142 - you scale painlessly to handle large projects.</para> 2.143 - 2.144 - <para id="x_7b">No revision control tool can rescue a poorly run project, 2.145 - but a good choice of tools can make a huge difference to the 2.146 - fluidity with which you can work on a project.</para> 2.147 - 2.148 - </sect2> 2.149 - 2.150 - <sect2> 2.151 - <title>The many names of revision control</title> 2.152 - 2.153 - <para id="x_7c">Revision control is a diverse field, so much so that it is 2.154 - referred to by many names and acronyms. Here are a few of the 2.155 - more common variations you'll encounter:</para> 2.156 - <itemizedlist> 2.157 - <listitem><para id="x_7d">Revision control (RCS)</para></listitem> 2.158 - <listitem><para id="x_7e">Software configuration management (SCM), or 2.159 - configuration management</para></listitem> 2.160 - <listitem><para id="x_7f">Source code management</para></listitem> 2.161 - <listitem><para id="x_80">Source code control, or source 2.162 - control</para></listitem> 2.163 - <listitem><para id="x_81">Version control 2.164 - (VCS)</para></listitem></itemizedlist> 2.165 - <para id="x_82">Some people claim that these terms actually have different 2.166 - meanings, but in practice they overlap so much that there's no 2.167 - agreed or even useful way to tease them apart.</para> 2.168 - 2.169 - </sect2> 2.170 + <caution> 2.171 + <para>This icon indicates a warning or caution.</para> 2.172 + </caution> 2.173 </sect1> 2.174 2.175 <sect1> 2.176 - <title>This book is a work in progress</title> 2.177 + <title>Using Code Examples</title> 2.178 2.179 - <para id="x_83">I am releasing this book while I am still writing it, in the 2.180 - hope that it will prove useful to others. I am writing under an 2.181 - open license in the hope that you, my readers, will contribute 2.182 - feedback and perhaps content of your own.</para> 2.183 + <para>This book is here to help you get your job done. In general, 2.184 + you may use the code in this book in your programs and 2.185 + documentation. You do not need to contact us for permission 2.186 + unless you’re reproducing a significant portion of the code. For 2.187 + example, writing a program that uses several chunks of code from 2.188 + this book does not require permission. Selling or distributing a 2.189 + CD-ROM of examples from O’Reilly books does require permission. 2.190 + Answering a question by citing this book and quoting example 2.191 + code does not require permission. Incorporating a significant 2.192 + amount of example code from this book into your product’s 2.193 + documentation does require permission.</para> 2.194 2.195 - </sect1> 2.196 - <sect1> 2.197 - <title>About the examples in this book</title> 2.198 + <para>We appreciate, but do not require, attribution. An 2.199 + attribution usually includes the title, author, publisher, and 2.200 + ISBN. For example: “<emphasis>Book Title</emphasis> by Some 2.201 + Author. Copyright 2008 O’Reilly Media, Inc., 2.202 + 978-0-596-xxxx-x.”</para> 2.203 2.204 - <para id="x_84">This book takes an unusual approach to code samples. Every 2.205 - example is <quote>live</quote>&emdash;each one is actually the result 2.206 - of a shell script that executes the Mercurial commands you see. 2.207 - Every time an image of the book is built from its sources, all 2.208 - the example scripts are automatically run, and their current 2.209 - results compared against their expected results.</para> 2.210 - 2.211 - <para id="x_85">The advantage of this approach is that the examples are 2.212 - always accurate; they describe <emphasis>exactly</emphasis> the 2.213 - behavior of the version of Mercurial that's mentioned at the 2.214 - front of the book. If I update the version of Mercurial that 2.215 - I'm documenting, and the output of some command changes, the 2.216 - build fails.</para> 2.217 - 2.218 - <para id="x_86">There is a small disadvantage to this approach, which is 2.219 - that the dates and times you'll see in examples tend to be 2.220 - <quote>squashed</quote> together in a way that they wouldn't be 2.221 - if the same commands were being typed by a human. Where a human 2.222 - can issue no more than one command every few seconds, with any 2.223 - resulting timestamps correspondingly spread out, my automated 2.224 - example scripts run many commands in one second.</para> 2.225 - 2.226 - <para id="x_87">As an instance of this, several consecutive commits in an 2.227 - example can show up as having occurred during the same second. 2.228 - You can see this occur in the <literal 2.229 - role="hg-ext">bisect</literal> example in <xref 2.230 - linkend="sec:undo:bisect"/>, for instance.</para> 2.231 - 2.232 - <para id="x_88">So when you're reading examples, don't place too much weight 2.233 - on the dates or times you see in the output of commands. But 2.234 - <emphasis>do</emphasis> be confident that the behavior you're 2.235 - seeing is consistent and reproducible.</para> 2.236 - 2.237 + <para>If you feel your use of code examples falls outside fair use 2.238 + or the permission given above, feel free to contact us at 2.239 + <email>permissions@oreilly.com</email>.</para> 2.240 </sect1> 2.241 2.242 <sect1> 2.243 - <title>Trends in the field</title> 2.244 + <title>Safari® Books Online</title> 2.245 2.246 - <para id="x_89">There has been an unmistakable trend in the development and 2.247 - use of revision control tools over the past four decades, as 2.248 - people have become familiar with the capabilities of their tools 2.249 - and constrained by their limitations.</para> 2.250 + <note role="safarienabled"> 2.251 + <para>When you see a Safari® Books Online icon on the cover of 2.252 + your favorite technology book, that means the book is 2.253 + available online through the O’Reilly Network Safari 2.254 + Bookshelf.</para> 2.255 + </note> 2.256 2.257 - <para id="x_8a">The first generation began by managing single files on 2.258 - individual computers. Although these tools represented a huge 2.259 - advance over ad-hoc manual revision control, their locking model 2.260 - and reliance on a single computer limited them to small, 2.261 - tightly-knit teams.</para> 2.262 - 2.263 - <para id="x_8b">The second generation loosened these constraints by moving 2.264 - to network-centered architectures, and managing entire projects 2.265 - at a time. As projects grew larger, they ran into new problems. 2.266 - With clients needing to talk to servers very frequently, server 2.267 - scaling became an issue for large projects. An unreliable 2.268 - network connection could prevent remote users from being able to 2.269 - talk to the server at all. As open source projects started 2.270 - making read-only access available anonymously to anyone, people 2.271 - without commit privileges found that they could not use the 2.272 - tools to interact with a project in a natural way, as they could 2.273 - not record their changes.</para> 2.274 - 2.275 - <para id="x_8c">The current generation of revision control tools is 2.276 - peer-to-peer in nature. All of these systems have dropped the 2.277 - dependency on a single central server, and allow people to 2.278 - distribute their revision control data to where it's actually 2.279 - needed. Collaboration over the Internet has moved from 2.280 - constrained by technology to a matter of choice and consensus. 2.281 - Modern tools can operate offline indefinitely and autonomously, 2.282 - with a network connection only needed when syncing changes with 2.283 - another repository.</para> 2.284 - 2.285 - </sect1> 2.286 - <sect1> 2.287 - <title>A few of the advantages of distributed revision 2.288 - control</title> 2.289 - 2.290 - <para id="x_8d">Even though distributed revision control tools have for 2.291 - several years been as robust and usable as their 2.292 - previous-generation counterparts, people using older tools have 2.293 - not yet necessarily woken up to their advantages. There are a 2.294 - number of ways in which distributed tools shine relative to 2.295 - centralised ones.</para> 2.296 - 2.297 - <para id="x_8e">For an individual developer, distributed tools are almost 2.298 - always much faster than centralised tools. This is for a simple 2.299 - reason: a centralised tool needs to talk over the network for 2.300 - many common operations, because most metadata is stored in a 2.301 - single copy on the central server. A distributed tool stores 2.302 - all of its metadata locally. All else being equal, talking over 2.303 - the network adds overhead to a centralised tool. Don't 2.304 - underestimate the value of a snappy, responsive tool: you're 2.305 - going to spend a lot of time interacting with your revision 2.306 - control software.</para> 2.307 - 2.308 - <para id="x_8f">Distributed tools are indifferent to the vagaries of your 2.309 - server infrastructure, again because they replicate metadata to 2.310 - so many locations. If you use a centralised system and your 2.311 - server catches fire, you'd better hope that your backup media 2.312 - are reliable, and that your last backup was recent and actually 2.313 - worked. With a distributed tool, you have many backups 2.314 - available on every contributor's computer.</para> 2.315 - 2.316 - <para id="x_90">The reliability of your network will affect distributed 2.317 - tools far less than it will centralised tools. You can't even 2.318 - use a centralised tool without a network connection, except for 2.319 - a few highly constrained commands. With a distributed tool, if 2.320 - your network connection goes down while you're working, you may 2.321 - not even notice. The only thing you won't be able to do is talk 2.322 - to repositories on other computers, something that is relatively 2.323 - rare compared with local operations. If you have a far-flung 2.324 - team of collaborators, this may be significant.</para> 2.325 - 2.326 - <sect2> 2.327 - <title>Advantages for open source projects</title> 2.328 - 2.329 - <para id="x_91">If you take a shine to an open source project and decide 2.330 - that you would like to start hacking on it, and that project 2.331 - uses a distributed revision control tool, you are at once a 2.332 - peer with the people who consider themselves the 2.333 - <quote>core</quote> of that project. If they publish their 2.334 - repositories, you can immediately copy their project history, 2.335 - start making changes, and record your work, using the same 2.336 - tools in the same ways as insiders. By contrast, with a 2.337 - centralised tool, you must use the software in a <quote>read 2.338 - only</quote> mode unless someone grants you permission to 2.339 - commit changes to their central server. Until then, you won't 2.340 - be able to record changes, and your local modifications will 2.341 - be at risk of corruption any time you try to update your 2.342 - client's view of the repository.</para> 2.343 - 2.344 - <sect3> 2.345 - <title>The forking non-problem</title> 2.346 - 2.347 - <para id="x_92">It has been suggested that distributed revision control 2.348 - tools pose some sort of risk to open source projects because 2.349 - they make it easy to <quote>fork</quote> the development of 2.350 - a project. A fork happens when there are differences in 2.351 - opinion or attitude between groups of developers that cause 2.352 - them to decide that they can't work together any longer. 2.353 - Each side takes a more or less complete copy of the 2.354 - project's source code, and goes off in its own 2.355 - direction.</para> 2.356 - 2.357 - <para id="x_93">Sometimes the camps in a fork decide to reconcile their 2.358 - differences. With a centralised revision control system, the 2.359 - <emphasis>technical</emphasis> process of reconciliation is 2.360 - painful, and has to be performed largely by hand. You have 2.361 - to decide whose revision history is going to 2.362 - <quote>win</quote>, and graft the other team's changes into 2.363 - the tree somehow. This usually loses some or all of one 2.364 - side's revision history.</para> 2.365 - 2.366 - <para id="x_94">What distributed tools do with respect to forking is 2.367 - they make forking the <emphasis>only</emphasis> way to 2.368 - develop a project. Every single change that you make is 2.369 - potentially a fork point. The great strength of this 2.370 - approach is that a distributed revision control tool has to 2.371 - be really good at <emphasis>merging</emphasis> forks, 2.372 - because forks are absolutely fundamental: they happen all 2.373 - the time.</para> 2.374 - 2.375 - <para id="x_95">If every piece of work that everybody does, all the 2.376 - time, is framed in terms of forking and merging, then what 2.377 - the open source world refers to as a <quote>fork</quote> 2.378 - becomes <emphasis>purely</emphasis> a social issue. If 2.379 - anything, distributed tools <emphasis>lower</emphasis> the 2.380 - likelihood of a fork:</para> 2.381 - <itemizedlist> 2.382 - <listitem><para id="x_96">They eliminate the social distinction that 2.383 - centralised tools impose: that between insiders (people 2.384 - with commit access) and outsiders (people 2.385 - without).</para></listitem> 2.386 - <listitem><para id="x_97">They make it easier to reconcile after a 2.387 - social fork, because all that's involved from the 2.388 - perspective of the revision control software is just 2.389 - another merge.</para></listitem></itemizedlist> 2.390 - 2.391 - <para id="x_98">Some people resist distributed tools because they want 2.392 - to retain tight control over their projects, and they 2.393 - believe that centralised tools give them this control. 2.394 - However, if you're of this belief, and you publish your CVS 2.395 - or Subversion repositories publicly, there are plenty of 2.396 - tools available that can pull out your entire project's 2.397 - history (albeit slowly) and recreate it somewhere that you 2.398 - don't control. So while your control in this case is 2.399 - illusory, you are forgoing the ability to fluidly 2.400 - collaborate with whatever people feel compelled to mirror 2.401 - and fork your history.</para> 2.402 - 2.403 - </sect3> 2.404 - </sect2> 2.405 - <sect2> 2.406 - <title>Advantages for commercial projects</title> 2.407 - 2.408 - <para id="x_99">Many commercial projects are undertaken by teams that are 2.409 - scattered across the globe. Contributors who are far from a 2.410 - central server will see slower command execution and perhaps 2.411 - less reliability. Commercial revision control systems attempt 2.412 - to ameliorate these problems with remote-site replication 2.413 - add-ons that are typically expensive to buy and cantankerous 2.414 - to administer. A distributed system doesn't suffer from these 2.415 - problems in the first place. Better yet, you can easily set 2.416 - up multiple authoritative servers, say one per site, so that 2.417 - there's no redundant communication between repositories over 2.418 - expensive long-haul network links.</para> 2.419 - 2.420 - <para id="x_9a">Centralised revision control systems tend to have 2.421 - relatively low scalability. It's not unusual for an expensive 2.422 - centralised system to fall over under the combined load of 2.423 - just a few dozen concurrent users. Once again, the typical 2.424 - response tends to be an expensive and clunky replication 2.425 - facility. Since the load on a central server&emdash;if you have 2.426 - one at all&emdash;is many times lower with a distributed tool 2.427 - (because all of the data is replicated everywhere), a single 2.428 - cheap server can handle the needs of a much larger team, and 2.429 - replication to balance load becomes a simple matter of 2.430 - scripting.</para> 2.431 - 2.432 - <para id="x_9b">If you have an employee in the field, troubleshooting a 2.433 - problem at a customer's site, they'll benefit from distributed 2.434 - revision control. The tool will let them generate custom 2.435 - builds, try different fixes in isolation from each other, and 2.436 - search efficiently through history for the sources of bugs and 2.437 - regressions in the customer's environment, all without needing 2.438 - to connect to your company's network.</para> 2.439 - 2.440 - </sect2> 2.441 - </sect1> 2.442 - <sect1> 2.443 - <title>Why choose Mercurial?</title> 2.444 - 2.445 - <para id="x_9c">Mercurial has a unique set of properties that make it a 2.446 - particularly good choice as a revision control system.</para> 2.447 - <itemizedlist> 2.448 - <listitem><para id="x_9d">It is easy to learn and use.</para></listitem> 2.449 - <listitem><para id="x_9e">It is lightweight.</para></listitem> 2.450 - <listitem><para id="x_9f">It scales excellently.</para></listitem> 2.451 - <listitem><para id="x_a0">It is easy to 2.452 - customise.</para></listitem></itemizedlist> 2.453 - 2.454 - <para id="x_a1">If you are at all familiar with revision control systems, 2.455 - you should be able to get up and running with Mercurial in less 2.456 - than five minutes. Even if not, it will take no more than a few 2.457 - minutes longer. Mercurial's command and feature sets are 2.458 - generally uniform and consistent, so you can keep track of a few 2.459 - general rules instead of a host of exceptions.</para> 2.460 - 2.461 - <para id="x_a2">On a small project, you can start working with Mercurial in 2.462 - moments. Creating new changes and branches; transferring changes 2.463 - around (whether locally or over a network); and history and 2.464 - status operations are all fast. Mercurial attempts to stay 2.465 - nimble and largely out of your way by combining low cognitive 2.466 - overhead with blazingly fast operations.</para> 2.467 - 2.468 - <para id="x_a3">The usefulness of Mercurial is not limited to small 2.469 - projects: it is used by projects with hundreds to thousands of 2.470 - contributors, each containing tens of thousands of files and 2.471 - hundreds of megabytes of source code.</para> 2.472 - 2.473 - <para id="x_a4">If the core functionality of Mercurial is not enough for 2.474 - you, it's easy to build on. Mercurial is well suited to 2.475 - scripting tasks, and its clean internals and implementation in 2.476 - Python make it easy to add features in the form of extensions. 2.477 - There are a number of popular and useful extensions already 2.478 - available, ranging from helping to identify bugs to improving 2.479 - performance.</para> 2.480 - 2.481 - </sect1> 2.482 - <sect1> 2.483 - <title>Mercurial compared with other tools</title> 2.484 - 2.485 - <para id="x_a5">Before you read on, please understand that this section 2.486 - necessarily reflects my own experiences, interests, and (dare I 2.487 - say it) biases. I have used every one of the revision control 2.488 - tools listed below, in most cases for several years at a 2.489 - time.</para> 2.490 - 2.491 - 2.492 - <sect2> 2.493 - <title>Subversion</title> 2.494 - 2.495 - <para id="x_a6">Subversion is a popular revision control tool, developed 2.496 - to replace CVS. It has a centralised client/server 2.497 - architecture.</para> 2.498 - 2.499 - <para id="x_a7">Subversion and Mercurial have similarly named commands for 2.500 - performing the same operations, so if you're familiar with 2.501 - one, it is easy to learn to use the other. Both tools are 2.502 - portable to all popular operating systems.</para> 2.503 - 2.504 - <para id="x_a8">Prior to version 1.5, Subversion had no useful support for 2.505 - merges. At the time of writing, its merge tracking capability 2.506 - is new, and known to be <ulink 2.507 - url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 2.508 - and buggy</ulink>.</para> 2.509 - 2.510 - <para id="x_a9">Mercurial has a substantial performance advantage over 2.511 - Subversion on every revision control operation I have 2.512 - benchmarked. I have measured its advantage as ranging from a 2.513 - factor of two to a factor of six when compared with Subversion 2.514 - 1.4.3's <emphasis>ra_local</emphasis> file store, which is the 2.515 - fastest access method available. In more realistic 2.516 - deployments involving a network-based store, Subversion will 2.517 - be at a substantially larger disadvantage. Because many 2.518 - Subversion commands must talk to the server and Subversion 2.519 - does not have useful replication facilities, server capacity 2.520 - and network bandwidth become bottlenecks for modestly large 2.521 - projects.</para> 2.522 - 2.523 - <para id="x_aa">Additionally, Subversion incurs substantial storage 2.524 - overhead to avoid network transactions for a few common 2.525 - operations, such as finding modified files 2.526 - (<literal>status</literal>) and displaying modifications 2.527 - against the current revision (<literal>diff</literal>). As a 2.528 - result, a Subversion working copy is often the same size as, 2.529 - or larger than, a Mercurial repository and working directory, 2.530 - even though the Mercurial repository contains a complete 2.531 - history of the project.</para> 2.532 - 2.533 - <para id="x_ab">Subversion is widely supported by third party tools. 2.534 - Mercurial currently lags considerably in this area. This gap 2.535 - is closing, however, and indeed some of Mercurial's GUI tools 2.536 - now outshine their Subversion equivalents. Like Mercurial, 2.537 - Subversion has an excellent user manual.</para> 2.538 - 2.539 - <para id="x_ac">Because Subversion doesn't store revision history on the 2.540 - client, it is well suited to managing projects that deal with 2.541 - lots of large, opaque binary files. If you check in fifty 2.542 - revisions to an incompressible 10MB file, Subversion's 2.543 - client-side space usage stays constant The space used by any 2.544 - distributed SCM will grow rapidly in proportion to the number 2.545 - of revisions, because the differences between each revision 2.546 - are large.</para> 2.547 - 2.548 - <para id="x_ad">In addition, it's often difficult or, more usually, 2.549 - impossible to merge different versions of a binary file. 2.550 - Subversion's ability to let a user lock a file, so that they 2.551 - temporarily have the exclusive right to commit changes to it, 2.552 - can be a significant advantage to a project where binary files 2.553 - are widely used.</para> 2.554 - 2.555 - <para id="x_ae">Mercurial can import revision history from a Subversion 2.556 - repository. It can also export revision history to a 2.557 - Subversion repository. This makes it easy to <quote>test the 2.558 - waters</quote> and use Mercurial and Subversion in parallel 2.559 - before deciding to switch. History conversion is incremental, 2.560 - so you can perform an initial conversion, then small 2.561 - additional conversions afterwards to bring in new 2.562 - changes.</para> 2.563 - 2.564 - 2.565 - </sect2> 2.566 - <sect2> 2.567 - <title>Git</title> 2.568 - 2.569 - <para id="x_af">Git is a distributed revision control tool that was 2.570 - developed for managing the Linux kernel source tree. Like 2.571 - Mercurial, its early design was somewhat influenced by 2.572 - Monotone.</para> 2.573 - 2.574 - <para id="x_b0">Git has a very large command set, with version 1.5.0 2.575 - providing 139 individual commands. It has something of a 2.576 - reputation for being difficult to learn. Compared to Git, 2.577 - Mercurial has a strong focus on simplicity.</para> 2.578 - 2.579 - <para id="x_b1">In terms of performance, Git is extremely fast. In 2.580 - several cases, it is faster than Mercurial, at least on Linux, 2.581 - while Mercurial performs better on other operations. However, 2.582 - on Windows, the performance and general level of support that 2.583 - Git provides is, at the time of writing, far behind that of 2.584 - Mercurial.</para> 2.585 - 2.586 - <para id="x_b2">While a Mercurial repository needs no maintenance, a Git 2.587 - repository requires frequent manual <quote>repacks</quote> of 2.588 - its metadata. Without these, performance degrades, while 2.589 - space usage grows rapidly. A server that contains many Git 2.590 - repositories that are not rigorously and frequently repacked 2.591 - will become heavily disk-bound during backups, and there have 2.592 - been instances of daily backups taking far longer than 24 2.593 - hours as a result. A freshly packed Git repository is 2.594 - slightly smaller than a Mercurial repository, but an unpacked 2.595 - repository is several orders of magnitude larger.</para> 2.596 - 2.597 - <para id="x_b3">The core of Git is written in C. Many Git commands are 2.598 - implemented as shell or Perl scripts, and the quality of these 2.599 - scripts varies widely. I have encountered several instances 2.600 - where scripts charged along blindly in the presence of errors 2.601 - that should have been fatal.</para> 2.602 - 2.603 - <para id="x_b4">Mercurial can import revision history from a Git 2.604 - repository.</para> 2.605 - 2.606 - 2.607 - </sect2> 2.608 - <sect2> 2.609 - <title>CVS</title> 2.610 - 2.611 - <para id="x_b5">CVS is probably the most widely used revision control tool 2.612 - in the world. Due to its age and internal untidiness, it has 2.613 - been only lightly maintained for many years.</para> 2.614 - 2.615 - <para id="x_b6">It has a centralised client/server architecture. It does 2.616 - not group related file changes into atomic commits, making it 2.617 - easy for people to <quote>break the build</quote>: one person 2.618 - can successfully commit part of a change and then be blocked 2.619 - by the need for a merge, causing other people to see only a 2.620 - portion of the work they intended to do. This also affects 2.621 - how you work with project history. If you want to see all of 2.622 - the modifications someone made as part of a task, you will 2.623 - need to manually inspect the descriptions and timestamps of 2.624 - the changes made to each file involved (if you even know what 2.625 - those files were).</para> 2.626 - 2.627 - <para id="x_b7">CVS has a muddled notion of tags and branches that I will 2.628 - not attempt to even describe. It does not support renaming of 2.629 - files or directories well, making it easy to corrupt a 2.630 - repository. It has almost no internal consistency checking 2.631 - capabilities, so it is usually not even possible to tell 2.632 - whether or how a repository is corrupt. I would not recommend 2.633 - CVS for any project, existing or new.</para> 2.634 - 2.635 - <para id="x_b8">Mercurial can import CVS revision history. However, there 2.636 - are a few caveats that apply; these are true of every other 2.637 - revision control tool's CVS importer, too. Due to CVS's lack 2.638 - of atomic changes and unversioned filesystem hierarchy, it is 2.639 - not possible to reconstruct CVS history completely accurately; 2.640 - some guesswork is involved, and renames will usually not show 2.641 - up. Because a lot of advanced CVS administration has to be 2.642 - done by hand and is hence error-prone, it's common for CVS 2.643 - importers to run into multiple problems with corrupted 2.644 - repositories (completely bogus revision timestamps and files 2.645 - that have remained locked for over a decade are just two of 2.646 - the less interesting problems I can recall from personal 2.647 - experience).</para> 2.648 - 2.649 - <para id="x_b9">Mercurial can import revision history from a CVS 2.650 - repository.</para> 2.651 - 2.652 - 2.653 - </sect2> 2.654 - <sect2> 2.655 - <title>Commercial tools</title> 2.656 - 2.657 - <para id="x_ba">Perforce has a centralised client/server architecture, 2.658 - with no client-side caching of any data. Unlike modern 2.659 - revision control tools, Perforce requires that a user run a 2.660 - command to inform the server about every file they intend to 2.661 - edit.</para> 2.662 - 2.663 - <para id="x_bb">The performance of Perforce is quite good for small teams, 2.664 - but it falls off rapidly as the number of users grows beyond a 2.665 - few dozen. Modestly large Perforce installations require the 2.666 - deployment of proxies to cope with the load their users 2.667 - generate.</para> 2.668 - 2.669 - 2.670 - </sect2> 2.671 - <sect2> 2.672 - <title>Choosing a revision control tool</title> 2.673 - 2.674 - <para id="x_bc">With the exception of CVS, all of the tools listed above 2.675 - have unique strengths that suit them to particular styles of 2.676 - work. There is no single revision control tool that is best 2.677 - in all situations.</para> 2.678 - 2.679 - <para id="x_bd">As an example, Subversion is a good choice for working 2.680 - with frequently edited binary files, due to its centralised 2.681 - nature and support for file locking.</para> 2.682 - 2.683 - <para id="x_be">I personally find Mercurial's properties of simplicity, 2.684 - performance, and good merge support to be a compelling 2.685 - combination that has served me well for several years.</para> 2.686 - 2.687 - 2.688 - </sect2> 2.689 - </sect1> 2.690 - <sect1> 2.691 - <title>Switching from another tool to Mercurial</title> 2.692 - 2.693 - <para id="x_bf">Mercurial is bundled with an extension named <literal 2.694 - role="hg-ext">convert</literal>, which can incrementally 2.695 - import revision history from several other revision control 2.696 - tools. By <quote>incremental</quote>, I mean that you can 2.697 - convert all of a project's history to date in one go, then rerun 2.698 - the conversion later to obtain new changes that happened after 2.699 - the initial conversion.</para> 2.700 - 2.701 - <para id="x_c0">The revision control tools supported by <literal 2.702 - role="hg-ext">convert</literal> are as follows:</para> 2.703 - <itemizedlist> 2.704 - <listitem><para id="x_c1">Subversion</para></listitem> 2.705 - <listitem><para id="x_c2">CVS</para></listitem> 2.706 - <listitem><para id="x_c3">Git</para></listitem> 2.707 - <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist> 2.708 - 2.709 - <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can 2.710 - export changes from Mercurial to Subversion. This makes it 2.711 - possible to try Subversion and Mercurial in parallel before 2.712 - committing to a switchover, without risking the loss of any 2.713 - work.</para> 2.714 - 2.715 - <para id="x_c6">The <command role="hg-ext-convert">convert</command> command 2.716 - is easy to use. Simply point it at the path or URL of the 2.717 - source repository, optionally give it the name of the 2.718 - destination repository, and it will start working. After the 2.719 - initial conversion, just run the same command again to import 2.720 - new changes.</para> 2.721 + <para>Safari offers a solution that’s better than e-books. It’s a 2.722 + virtual library that lets you easily search thousands of top 2.723 + tech books, cut and paste code samples, download chapters, and 2.724 + find quick answers when you need the most accurate, current 2.725 + information. Try it for free at <ulink role="orm:hideurl:ital" 2.726 + url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para> 2.727 </sect1> 2.728 2.729 <sect1> 2.730 - <title>A short history of revision control</title> 2.731 + <title>How to Contact Us</title> 2.732 2.733 - <para id="x_c7">The best known of the old-time revision control tools is 2.734 - SCCS (Source Code Control System), which Marc Rochkind wrote at 2.735 - Bell Labs, in the early 1970s. SCCS operated on individual 2.736 - files, and required every person working on a project to have 2.737 - access to a shared workspace on a single system. Only one 2.738 - person could modify a file at any time; arbitration for access 2.739 - to files was via locks. It was common for people to lock files, 2.740 - and later forget to unlock them, preventing anyone else from 2.741 - modifying those files without the help of an 2.742 - administrator.</para> 2.743 + <para>Please address comments and questions concerning this book 2.744 + to the publisher:</para> 2.745 2.746 - <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the 2.747 - early 1980s; he called his program RCS (Revision Control System). 2.748 - Like SCCS, RCS required developers to work in a single shared 2.749 - workspace, and to lock files to prevent multiple people from 2.750 - modifying them simultaneously.</para> 2.751 + <simplelist type="vert"> 2.752 + <member>O’Reilly Media, Inc.</member> 2.753 2.754 - <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block 2.755 - for a set of shell scripts he initially called cmt, but then 2.756 - renamed to CVS (Concurrent Versions System). The big innovation 2.757 - of CVS was that it let developers work simultaneously and 2.758 - somewhat independently in their own personal workspaces. The 2.759 - personal workspaces prevented developers from stepping on each 2.760 - other's toes all the time, as was common with SCCS and RCS. Each 2.761 - developer had a copy of every project file, and could modify 2.762 - their copies independently. They had to merge their edits prior 2.763 - to committing changes to the central repository.</para> 2.764 + <member>1005 Gravenstein Highway North</member> 2.765 2.766 - <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote 2.767 - them in C, releasing in 1989 the code that has since developed 2.768 - into the modern version of CVS. CVS subsequently acquired the 2.769 - ability to operate over a network connection, giving it a 2.770 - client/server architecture. CVS's architecture is centralised; 2.771 - only the server has a copy of the history of the project. Client 2.772 - workspaces just contain copies of recent versions of the 2.773 - project's files, and a little metadata to tell them where the 2.774 - server is. CVS has been enormously successful; it is probably 2.775 - the world's most widely used revision control system.</para> 2.776 + <member>Sebastopol, CA 95472</member> 2.777 2.778 - <para id="x_cb">In the early 1990s, Sun Microsystems developed an early 2.779 - distributed revision control system, called TeamWare. A 2.780 - TeamWare workspace contains a complete copy of the project's 2.781 - history. TeamWare has no notion of a central repository. (CVS 2.782 - relied upon RCS for its history storage; TeamWare used 2.783 - SCCS.)</para> 2.784 + <member>800-998-9938 (in the United States or Canada)</member> 2.785 2.786 - <para id="x_cc">As the 1990s progressed, awareness grew of a number of 2.787 - problems with CVS. It records simultaneous changes to multiple 2.788 - files individually, instead of grouping them together as a 2.789 - single logically atomic operation. It does not manage its file 2.790 - hierarchy well; it is easy to make a mess of a repository by 2.791 - renaming files and directories. Worse, its source code is 2.792 - difficult to read and maintain, which made the <quote>pain 2.793 - level</quote> of fixing these architectural problems 2.794 - prohibitive.</para> 2.795 + <member>707-829-0515 (international or local)</member> 2.796 2.797 - <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had 2.798 - worked on CVS, started a project to replace it with a tool that 2.799 - would have a better architecture and cleaner code. The result, 2.800 - Subversion, does not stray from CVS's centralised client/server 2.801 - model, but it adds multi-file atomic commits, better namespace 2.802 - management, and a number of other features that make it a 2.803 - generally better tool than CVS. Since its initial release, it 2.804 - has rapidly grown in popularity.</para> 2.805 + <member>707 829-0104 (fax)</member> 2.806 + </simplelist> 2.807 2.808 - <para id="x_ce">More or less simultaneously, Graydon Hoare began working on 2.809 - an ambitious distributed revision control system that he named 2.810 - Monotone. While Monotone addresses many of CVS's design flaws 2.811 - and has a peer-to-peer architecture, it goes beyond earlier (and 2.812 - subsequent) revision control tools in a number of innovative 2.813 - ways. It uses cryptographic hashes as identifiers, and has an 2.814 - integral notion of <quote>trust</quote> for code from different 2.815 - sources.</para> 2.816 + <para>We have a web page for this book, where we list errata, 2.817 + examples, and any additional information. You can access this 2.818 + page at:</para> 2.819 2.820 - <para id="x_cf">Mercurial began life in 2005. While a few aspects of its 2.821 - design are influenced by Monotone, Mercurial focuses on ease of 2.822 - use, high performance, and scalability to very large 2.823 - projects.</para> 2.824 + <simplelist type="vert"> 2.825 + <member><ulink url="http://www.oreilly.com/catalog/<catalog 2.826 + page>"></ulink></member> 2.827 + </simplelist> 2.828 2.829 - </sect1> 2.830 + <remark>Don’t forget to update the <url> attribute, 2.831 + too.</remark> 2.832 2.833 - <sect1> 2.834 - <title>Colophon&emdash;this book is Free</title> 2.835 + <para>To comment or ask technical questions about this book, send 2.836 + email to:</para> 2.837 2.838 - <para id="x_d0">This book is licensed under the Open Publication License, 2.839 - and is produced entirely using Free Software tools. It is 2.840 - typeset with DocBook XML. Illustrations are drawn and rendered with 2.841 - <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para> 2.842 + <simplelist type="vert"> 2.843 + <member><email>bookquestions@oreilly.com</email></member> 2.844 + </simplelist> 2.845 2.846 - <para id="x_d1">The complete source code for this book is published as a 2.847 - Mercurial repository, at <ulink 2.848 - url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para> 2.849 + <para>For more information about our books, conferences, Resource 2.850 + Centers, and the O’Reilly Network, see our web site at:</para> 2.851 2.852 + <simplelist type="vert"> 2.853 + <member><ulink url="http://www.oreilly.com"></ulink></member> 2.854 + </simplelist> 2.855 </sect1> 2.856 </preface> 2.857 + 2.858 <!-- 2.859 local variables: 2.860 sgml-parent-document: ("00book.xml" "book" "preface")
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 3.2 +++ b/en/ch01-intro.xml Thu May 07 21:07:35 2009 -0700 3.3 @@ -0,0 +1,734 @@ 3.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 3.5 + 3.6 +<chapter id="chap:intro"> 3.7 + <?dbhtml filename="how-did-we-get-here.html"?> 3.8 + <title>How did we get here?</title> 3.9 + 3.10 + <sect1> 3.11 + <title>Why revision control? Why Mercurial?</title> 3.12 + 3.13 + <para id="x_6d">Revision control is the process of managing multiple 3.14 + versions of a piece of information. In its simplest form, this 3.15 + is something that many people do by hand: every time you modify 3.16 + a file, save it under a new name that contains a number, each 3.17 + one higher than the number of the preceding version.</para> 3.18 + 3.19 + <para id="x_6e">Manually managing multiple versions of even a single file is 3.20 + an error-prone task, though, so software tools to help automate 3.21 + this process have long been available. The earliest automated 3.22 + revision control tools were intended to help a single user to 3.23 + manage revisions of a single file. Over the past few decades, 3.24 + the scope of revision control tools has expanded greatly; they 3.25 + now manage multiple files, and help multiple people to work 3.26 + together. The best modern revision control tools have no 3.27 + problem coping with thousands of people working together on 3.28 + projects that consist of hundreds of thousands of files.</para> 3.29 + 3.30 + <para id="x_6f">The arrival of distributed revision control is relatively 3.31 + recent, and so far this new field has grown due to people's 3.32 + willingness to explore ill-charted territory.</para> 3.33 + 3.34 + <para id="x_70">I am writing a book about distributed revision control 3.35 + because I believe that it is an important subject that deserves 3.36 + a field guide. I chose to write about Mercurial because it is 3.37 + the easiest tool to learn the terrain with, and yet it scales to 3.38 + the demands of real, challenging environments where many other 3.39 + revision control tools buckle.</para> 3.40 + 3.41 + <sect2> 3.42 + <title>Why use revision control?</title> 3.43 + 3.44 + <para id="x_71">There are a number of reasons why you or your team might 3.45 + want to use an automated revision control tool for a 3.46 + project.</para> 3.47 + 3.48 + <itemizedlist> 3.49 + <listitem><para id="x_72">It will track the history and evolution of 3.50 + your project, so you don't have to. For every change, 3.51 + you'll have a log of <emphasis>who</emphasis> made it; 3.52 + <emphasis>why</emphasis> they made it; 3.53 + <emphasis>when</emphasis> they made it; and 3.54 + <emphasis>what</emphasis> the change 3.55 + was.</para></listitem> 3.56 + <listitem><para id="x_73">When you're working with other people, 3.57 + revision control software makes it easier for you to 3.58 + collaborate. For example, when people more or less 3.59 + simultaneously make potentially incompatible changes, the 3.60 + software will help you to identify and resolve those 3.61 + conflicts.</para></listitem> 3.62 + <listitem><para id="x_74">It can help you to recover from mistakes. If 3.63 + you make a change that later turns out to be in error, you 3.64 + can revert to an earlier version of one or more files. In 3.65 + fact, a <emphasis>really</emphasis> good revision control 3.66 + tool will even help you to efficiently figure out exactly 3.67 + when a problem was introduced (see <xref 3.68 + linkend="sec:undo:bisect"/> for details).</para></listitem> 3.69 + <listitem><para id="x_75">It will help you to work simultaneously on, 3.70 + and manage the drift between, multiple versions of your 3.71 + project.</para></listitem> 3.72 + </itemizedlist> 3.73 + 3.74 + <para id="x_76">Most of these reasons are equally 3.75 + valid&emdash;at least in theory&emdash;whether you're working 3.76 + on a project by yourself, or with a hundred other 3.77 + people.</para> 3.78 + 3.79 + <para id="x_77">A key question about the practicality of revision control 3.80 + at these two different scales (<quote>lone hacker</quote> and 3.81 + <quote>huge team</quote>) is how its 3.82 + <emphasis>benefits</emphasis> compare to its 3.83 + <emphasis>costs</emphasis>. A revision control tool that's 3.84 + difficult to understand or use is going to impose a high 3.85 + cost.</para> 3.86 + 3.87 + <para id="x_78">A five-hundred-person project is likely to collapse under 3.88 + its own weight almost immediately without a revision control 3.89 + tool and process. In this case, the cost of using revision 3.90 + control might hardly seem worth considering, since 3.91 + <emphasis>without</emphasis> it, failure is almost 3.92 + guaranteed.</para> 3.93 + 3.94 + <para id="x_79">On the other hand, a one-person <quote>quick hack</quote> 3.95 + might seem like a poor place to use a revision control tool, 3.96 + because surely the cost of using one must be close to the 3.97 + overall cost of the project. Right?</para> 3.98 + 3.99 + <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of 3.100 + these scales of development. You can learn the basics in just 3.101 + a few minutes, and due to its low overhead, you can apply 3.102 + revision control to the smallest of projects with ease. Its 3.103 + simplicity means you won't have a lot of abstruse concepts or 3.104 + command sequences competing for mental space with whatever 3.105 + you're <emphasis>really</emphasis> trying to do. At the same 3.106 + time, Mercurial's high performance and peer-to-peer nature let 3.107 + you scale painlessly to handle large projects.</para> 3.108 + 3.109 + <para id="x_7b">No revision control tool can rescue a poorly run project, 3.110 + but a good choice of tools can make a huge difference to the 3.111 + fluidity with which you can work on a project.</para> 3.112 + 3.113 + </sect2> 3.114 + 3.115 + <sect2> 3.116 + <title>The many names of revision control</title> 3.117 + 3.118 + <para id="x_7c">Revision control is a diverse field, so much so that it is 3.119 + referred to by many names and acronyms. Here are a few of the 3.120 + more common variations you'll encounter:</para> 3.121 + <itemizedlist> 3.122 + <listitem><para id="x_7d">Revision control (RCS)</para></listitem> 3.123 + <listitem><para id="x_7e">Software configuration management (SCM), or 3.124 + configuration management</para></listitem> 3.125 + <listitem><para id="x_7f">Source code management</para></listitem> 3.126 + <listitem><para id="x_80">Source code control, or source 3.127 + control</para></listitem> 3.128 + <listitem><para id="x_81">Version control 3.129 + (VCS)</para></listitem></itemizedlist> 3.130 + <para id="x_82">Some people claim that these terms actually have different 3.131 + meanings, but in practice they overlap so much that there's no 3.132 + agreed or even useful way to tease them apart.</para> 3.133 + 3.134 + </sect2> 3.135 + </sect1> 3.136 + 3.137 + <sect1> 3.138 + <title>About the examples in this book</title> 3.139 + 3.140 + <para id="x_84">This book takes an unusual approach to code samples. Every 3.141 + example is <quote>live</quote>&emdash;each one is actually the result 3.142 + of a shell script that executes the Mercurial commands you see. 3.143 + Every time an image of the book is built from its sources, all 3.144 + the example scripts are automatically run, and their current 3.145 + results compared against their expected results.</para> 3.146 + 3.147 + <para id="x_85">The advantage of this approach is that the examples are 3.148 + always accurate; they describe <emphasis>exactly</emphasis> the 3.149 + behavior of the version of Mercurial that's mentioned at the 3.150 + front of the book. If I update the version of Mercurial that 3.151 + I'm documenting, and the output of some command changes, the 3.152 + build fails.</para> 3.153 + 3.154 + <para id="x_86">There is a small disadvantage to this approach, which is 3.155 + that the dates and times you'll see in examples tend to be 3.156 + <quote>squashed</quote> together in a way that they wouldn't be 3.157 + if the same commands were being typed by a human. Where a human 3.158 + can issue no more than one command every few seconds, with any 3.159 + resulting timestamps correspondingly spread out, my automated 3.160 + example scripts run many commands in one second.</para> 3.161 + 3.162 + <para id="x_87">As an instance of this, several consecutive commits in an 3.163 + example can show up as having occurred during the same second. 3.164 + You can see this occur in the <literal 3.165 + role="hg-ext">bisect</literal> example in <xref 3.166 + linkend="sec:undo:bisect"/>, for instance.</para> 3.167 + 3.168 + <para id="x_88">So when you're reading examples, don't place too much weight 3.169 + on the dates or times you see in the output of commands. But 3.170 + <emphasis>do</emphasis> be confident that the behavior you're 3.171 + seeing is consistent and reproducible.</para> 3.172 + 3.173 + </sect1> 3.174 + 3.175 + <sect1> 3.176 + <title>Trends in the field</title> 3.177 + 3.178 + <para id="x_89">There has been an unmistakable trend in the development and 3.179 + use of revision control tools over the past four decades, as 3.180 + people have become familiar with the capabilities of their tools 3.181 + and constrained by their limitations.</para> 3.182 + 3.183 + <para id="x_8a">The first generation began by managing single files on 3.184 + individual computers. Although these tools represented a huge 3.185 + advance over ad-hoc manual revision control, their locking model 3.186 + and reliance on a single computer limited them to small, 3.187 + tightly-knit teams.</para> 3.188 + 3.189 + <para id="x_8b">The second generation loosened these constraints by moving 3.190 + to network-centered architectures, and managing entire projects 3.191 + at a time. As projects grew larger, they ran into new problems. 3.192 + With clients needing to talk to servers very frequently, server 3.193 + scaling became an issue for large projects. An unreliable 3.194 + network connection could prevent remote users from being able to 3.195 + talk to the server at all. As open source projects started 3.196 + making read-only access available anonymously to anyone, people 3.197 + without commit privileges found that they could not use the 3.198 + tools to interact with a project in a natural way, as they could 3.199 + not record their changes.</para> 3.200 + 3.201 + <para id="x_8c">The current generation of revision control tools is 3.202 + peer-to-peer in nature. All of these systems have dropped the 3.203 + dependency on a single central server, and allow people to 3.204 + distribute their revision control data to where it's actually 3.205 + needed. Collaboration over the Internet has moved from 3.206 + constrained by technology to a matter of choice and consensus. 3.207 + Modern tools can operate offline indefinitely and autonomously, 3.208 + with a network connection only needed when syncing changes with 3.209 + another repository.</para> 3.210 + 3.211 + </sect1> 3.212 + <sect1> 3.213 + <title>A few of the advantages of distributed revision 3.214 + control</title> 3.215 + 3.216 + <para id="x_8d">Even though distributed revision control tools have for 3.217 + several years been as robust and usable as their 3.218 + previous-generation counterparts, people using older tools have 3.219 + not yet necessarily woken up to their advantages. There are a 3.220 + number of ways in which distributed tools shine relative to 3.221 + centralised ones.</para> 3.222 + 3.223 + <para id="x_8e">For an individual developer, distributed tools are almost 3.224 + always much faster than centralised tools. This is for a simple 3.225 + reason: a centralised tool needs to talk over the network for 3.226 + many common operations, because most metadata is stored in a 3.227 + single copy on the central server. A distributed tool stores 3.228 + all of its metadata locally. All else being equal, talking over 3.229 + the network adds overhead to a centralised tool. Don't 3.230 + underestimate the value of a snappy, responsive tool: you're 3.231 + going to spend a lot of time interacting with your revision 3.232 + control software.</para> 3.233 + 3.234 + <para id="x_8f">Distributed tools are indifferent to the vagaries of your 3.235 + server infrastructure, again because they replicate metadata to 3.236 + so many locations. If you use a centralised system and your 3.237 + server catches fire, you'd better hope that your backup media 3.238 + are reliable, and that your last backup was recent and actually 3.239 + worked. With a distributed tool, you have many backups 3.240 + available on every contributor's computer.</para> 3.241 + 3.242 + <para id="x_90">The reliability of your network will affect distributed 3.243 + tools far less than it will centralised tools. You can't even 3.244 + use a centralised tool without a network connection, except for 3.245 + a few highly constrained commands. With a distributed tool, if 3.246 + your network connection goes down while you're working, you may 3.247 + not even notice. The only thing you won't be able to do is talk 3.248 + to repositories on other computers, something that is relatively 3.249 + rare compared with local operations. If you have a far-flung 3.250 + team of collaborators, this may be significant.</para> 3.251 + 3.252 + <sect2> 3.253 + <title>Advantages for open source projects</title> 3.254 + 3.255 + <para id="x_91">If you take a shine to an open source project and decide 3.256 + that you would like to start hacking on it, and that project 3.257 + uses a distributed revision control tool, you are at once a 3.258 + peer with the people who consider themselves the 3.259 + <quote>core</quote> of that project. If they publish their 3.260 + repositories, you can immediately copy their project history, 3.261 + start making changes, and record your work, using the same 3.262 + tools in the same ways as insiders. By contrast, with a 3.263 + centralised tool, you must use the software in a <quote>read 3.264 + only</quote> mode unless someone grants you permission to 3.265 + commit changes to their central server. Until then, you won't 3.266 + be able to record changes, and your local modifications will 3.267 + be at risk of corruption any time you try to update your 3.268 + client's view of the repository.</para> 3.269 + 3.270 + <sect3> 3.271 + <title>The forking non-problem</title> 3.272 + 3.273 + <para id="x_92">It has been suggested that distributed revision control 3.274 + tools pose some sort of risk to open source projects because 3.275 + they make it easy to <quote>fork</quote> the development of 3.276 + a project. A fork happens when there are differences in 3.277 + opinion or attitude between groups of developers that cause 3.278 + them to decide that they can't work together any longer. 3.279 + Each side takes a more or less complete copy of the 3.280 + project's source code, and goes off in its own 3.281 + direction.</para> 3.282 + 3.283 + <para id="x_93">Sometimes the camps in a fork decide to reconcile their 3.284 + differences. With a centralised revision control system, the 3.285 + <emphasis>technical</emphasis> process of reconciliation is 3.286 + painful, and has to be performed largely by hand. You have 3.287 + to decide whose revision history is going to 3.288 + <quote>win</quote>, and graft the other team's changes into 3.289 + the tree somehow. This usually loses some or all of one 3.290 + side's revision history.</para> 3.291 + 3.292 + <para id="x_94">What distributed tools do with respect to forking is 3.293 + they make forking the <emphasis>only</emphasis> way to 3.294 + develop a project. Every single change that you make is 3.295 + potentially a fork point. The great strength of this 3.296 + approach is that a distributed revision control tool has to 3.297 + be really good at <emphasis>merging</emphasis> forks, 3.298 + because forks are absolutely fundamental: they happen all 3.299 + the time.</para> 3.300 + 3.301 + <para id="x_95">If every piece of work that everybody does, all the 3.302 + time, is framed in terms of forking and merging, then what 3.303 + the open source world refers to as a <quote>fork</quote> 3.304 + becomes <emphasis>purely</emphasis> a social issue. If 3.305 + anything, distributed tools <emphasis>lower</emphasis> the 3.306 + likelihood of a fork:</para> 3.307 + <itemizedlist> 3.308 + <listitem><para id="x_96">They eliminate the social distinction that 3.309 + centralised tools impose: that between insiders (people 3.310 + with commit access) and outsiders (people 3.311 + without).</para></listitem> 3.312 + <listitem><para id="x_97">They make it easier to reconcile after a 3.313 + social fork, because all that's involved from the 3.314 + perspective of the revision control software is just 3.315 + another merge.</para></listitem></itemizedlist> 3.316 + 3.317 + <para id="x_98">Some people resist distributed tools because they want 3.318 + to retain tight control over their projects, and they 3.319 + believe that centralised tools give them this control. 3.320 + However, if you're of this belief, and you publish your CVS 3.321 + or Subversion repositories publicly, there are plenty of 3.322 + tools available that can pull out your entire project's 3.323 + history (albeit slowly) and recreate it somewhere that you 3.324 + don't control. So while your control in this case is 3.325 + illusory, you are forgoing the ability to fluidly 3.326 + collaborate with whatever people feel compelled to mirror 3.327 + and fork your history.</para> 3.328 + 3.329 + </sect3> 3.330 + </sect2> 3.331 + <sect2> 3.332 + <title>Advantages for commercial projects</title> 3.333 + 3.334 + <para id="x_99">Many commercial projects are undertaken by teams that are 3.335 + scattered across the globe. Contributors who are far from a 3.336 + central server will see slower command execution and perhaps 3.337 + less reliability. Commercial revision control systems attempt 3.338 + to ameliorate these problems with remote-site replication 3.339 + add-ons that are typically expensive to buy and cantankerous 3.340 + to administer. A distributed system doesn't suffer from these 3.341 + problems in the first place. Better yet, you can easily set 3.342 + up multiple authoritative servers, say one per site, so that 3.343 + there's no redundant communication between repositories over 3.344 + expensive long-haul network links.</para> 3.345 + 3.346 + <para id="x_9a">Centralised revision control systems tend to have 3.347 + relatively low scalability. It's not unusual for an expensive 3.348 + centralised system to fall over under the combined load of 3.349 + just a few dozen concurrent users. Once again, the typical 3.350 + response tends to be an expensive and clunky replication 3.351 + facility. Since the load on a central server&emdash;if you have 3.352 + one at all&emdash;is many times lower with a distributed tool 3.353 + (because all of the data is replicated everywhere), a single 3.354 + cheap server can handle the needs of a much larger team, and 3.355 + replication to balance load becomes a simple matter of 3.356 + scripting.</para> 3.357 + 3.358 + <para id="x_9b">If you have an employee in the field, troubleshooting a 3.359 + problem at a customer's site, they'll benefit from distributed 3.360 + revision control. The tool will let them generate custom 3.361 + builds, try different fixes in isolation from each other, and 3.362 + search efficiently through history for the sources of bugs and 3.363 + regressions in the customer's environment, all without needing 3.364 + to connect to your company's network.</para> 3.365 + 3.366 + </sect2> 3.367 + </sect1> 3.368 + <sect1> 3.369 + <title>Why choose Mercurial?</title> 3.370 + 3.371 + <para id="x_9c">Mercurial has a unique set of properties that make it a 3.372 + particularly good choice as a revision control system.</para> 3.373 + <itemizedlist> 3.374 + <listitem><para id="x_9d">It is easy to learn and use.</para></listitem> 3.375 + <listitem><para id="x_9e">It is lightweight.</para></listitem> 3.376 + <listitem><para id="x_9f">It scales excellently.</para></listitem> 3.377 + <listitem><para id="x_a0">It is easy to 3.378 + customise.</para></listitem></itemizedlist> 3.379 + 3.380 + <para id="x_a1">If you are at all familiar with revision control systems, 3.381 + you should be able to get up and running with Mercurial in less 3.382 + than five minutes. Even if not, it will take no more than a few 3.383 + minutes longer. Mercurial's command and feature sets are 3.384 + generally uniform and consistent, so you can keep track of a few 3.385 + general rules instead of a host of exceptions.</para> 3.386 + 3.387 + <para id="x_a2">On a small project, you can start working with Mercurial in 3.388 + moments. Creating new changes and branches; transferring changes 3.389 + around (whether locally or over a network); and history and 3.390 + status operations are all fast. Mercurial attempts to stay 3.391 + nimble and largely out of your way by combining low cognitive 3.392 + overhead with blazingly fast operations.</para> 3.393 + 3.394 + <para id="x_a3">The usefulness of Mercurial is not limited to small 3.395 + projects: it is used by projects with hundreds to thousands of 3.396 + contributors, each containing tens of thousands of files and 3.397 + hundreds of megabytes of source code.</para> 3.398 + 3.399 + <para id="x_a4">If the core functionality of Mercurial is not enough for 3.400 + you, it's easy to build on. Mercurial is well suited to 3.401 + scripting tasks, and its clean internals and implementation in 3.402 + Python make it easy to add features in the form of extensions. 3.403 + There are a number of popular and useful extensions already 3.404 + available, ranging from helping to identify bugs to improving 3.405 + performance.</para> 3.406 + 3.407 + </sect1> 3.408 + <sect1> 3.409 + <title>Mercurial compared with other tools</title> 3.410 + 3.411 + <para id="x_a5">Before you read on, please understand that this section 3.412 + necessarily reflects my own experiences, interests, and (dare I 3.413 + say it) biases. I have used every one of the revision control 3.414 + tools listed below, in most cases for several years at a 3.415 + time.</para> 3.416 + 3.417 + 3.418 + <sect2> 3.419 + <title>Subversion</title> 3.420 + 3.421 + <para id="x_a6">Subversion is a popular revision control tool, developed 3.422 + to replace CVS. It has a centralised client/server 3.423 + architecture.</para> 3.424 + 3.425 + <para id="x_a7">Subversion and Mercurial have similarly named commands for 3.426 + performing the same operations, so if you're familiar with 3.427 + one, it is easy to learn to use the other. Both tools are 3.428 + portable to all popular operating systems.</para> 3.429 + 3.430 + <para id="x_a8">Prior to version 1.5, Subversion had no useful support for 3.431 + merges. At the time of writing, its merge tracking capability 3.432 + is new, and known to be <ulink 3.433 + url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 3.434 + and buggy</ulink>.</para> 3.435 + 3.436 + <para id="x_a9">Mercurial has a substantial performance advantage over 3.437 + Subversion on every revision control operation I have 3.438 + benchmarked. I have measured its advantage as ranging from a 3.439 + factor of two to a factor of six when compared with Subversion 3.440 + 1.4.3's <emphasis>ra_local</emphasis> file store, which is the 3.441 + fastest access method available. In more realistic 3.442 + deployments involving a network-based store, Subversion will 3.443 + be at a substantially larger disadvantage. Because many 3.444 + Subversion commands must talk to the server and Subversion 3.445 + does not have useful replication facilities, server capacity 3.446 + and network bandwidth become bottlenecks for modestly large 3.447 + projects.</para> 3.448 + 3.449 + <para id="x_aa">Additionally, Subversion incurs substantial storage 3.450 + overhead to avoid network transactions for a few common 3.451 + operations, such as finding modified files 3.452 + (<literal>status</literal>) and displaying modifications 3.453 + against the current revision (<literal>diff</literal>). As a 3.454 + result, a Subversion working copy is often the same size as, 3.455 + or larger than, a Mercurial repository and working directory, 3.456 + even though the Mercurial repository contains a complete 3.457 + history of the project.</para> 3.458 + 3.459 + <para id="x_ab">Subversion is widely supported by third party tools. 3.460 + Mercurial currently lags considerably in this area. This gap 3.461 + is closing, however, and indeed some of Mercurial's GUI tools 3.462 + now outshine their Subversion equivalents. Like Mercurial, 3.463 + Subversion has an excellent user manual.</para> 3.464 + 3.465 + <para id="x_ac">Because Subversion doesn't store revision history on the 3.466 + client, it is well suited to managing projects that deal with 3.467 + lots of large, opaque binary files. If you check in fifty 3.468 + revisions to an incompressible 10MB file, Subversion's 3.469 + client-side space usage stays constant The space used by any 3.470 + distributed SCM will grow rapidly in proportion to the number 3.471 + of revisions, because the differences between each revision 3.472 + are large.</para> 3.473 + 3.474 + <para id="x_ad">In addition, it's often difficult or, more usually, 3.475 + impossible to merge different versions of a binary file. 3.476 + Subversion's ability to let a user lock a file, so that they 3.477 + temporarily have the exclusive right to commit changes to it, 3.478 + can be a significant advantage to a project where binary files 3.479 + are widely used.</para> 3.480 + 3.481 + <para id="x_ae">Mercurial can import revision history from a Subversion 3.482 + repository. It can also export revision history to a 3.483 + Subversion repository. This makes it easy to <quote>test the 3.484 + waters</quote> and use Mercurial and Subversion in parallel 3.485 + before deciding to switch. History conversion is incremental, 3.486 + so you can perform an initial conversion, then small 3.487 + additional conversions afterwards to bring in new 3.488 + changes.</para> 3.489 + 3.490 + 3.491 + </sect2> 3.492 + <sect2> 3.493 + <title>Git</title> 3.494 + 3.495 + <para id="x_af">Git is a distributed revision control tool that was 3.496 + developed for managing the Linux kernel source tree. Like 3.497 + Mercurial, its early design was somewhat influenced by 3.498 + Monotone.</para> 3.499 + 3.500 + <para id="x_b0">Git has a very large command set, with version 1.5.0 3.501 + providing 139 individual commands. It has something of a 3.502 + reputation for being difficult to learn. Compared to Git, 3.503 + Mercurial has a strong focus on simplicity.</para> 3.504 + 3.505 + <para id="x_b1">In terms of performance, Git is extremely fast. In 3.506 + several cases, it is faster than Mercurial, at least on Linux, 3.507 + while Mercurial performs better on other operations. However, 3.508 + on Windows, the performance and general level of support that 3.509 + Git provides is, at the time of writing, far behind that of 3.510 + Mercurial.</para> 3.511 + 3.512 + <para id="x_b2">While a Mercurial repository needs no maintenance, a Git 3.513 + repository requires frequent manual <quote>repacks</quote> of 3.514 + its metadata. Without these, performance degrades, while 3.515 + space usage grows rapidly. A server that contains many Git 3.516 + repositories that are not rigorously and frequently repacked 3.517 + will become heavily disk-bound during backups, and there have 3.518 + been instances of daily backups taking far longer than 24 3.519 + hours as a result. A freshly packed Git repository is 3.520 + slightly smaller than a Mercurial repository, but an unpacked 3.521 + repository is several orders of magnitude larger.</para> 3.522 + 3.523 + <para id="x_b3">The core of Git is written in C. Many Git commands are 3.524 + implemented as shell or Perl scripts, and the quality of these 3.525 + scripts varies widely. I have encountered several instances 3.526 + where scripts charged along blindly in the presence of errors 3.527 + that should have been fatal.</para> 3.528 + 3.529 + <para id="x_b4">Mercurial can import revision history from a Git 3.530 + repository.</para> 3.531 + 3.532 + 3.533 + </sect2> 3.534 + <sect2> 3.535 + <title>CVS</title> 3.536 + 3.537 + <para id="x_b5">CVS is probably the most widely used revision control tool 3.538 + in the world. Due to its age and internal untidiness, it has 3.539 + been only lightly maintained for many years.</para> 3.540 + 3.541 + <para id="x_b6">It has a centralised client/server architecture. It does 3.542 + not group related file changes into atomic commits, making it 3.543 + easy for people to <quote>break the build</quote>: one person 3.544 + can successfully commit part of a change and then be blocked 3.545 + by the need for a merge, causing other people to see only a 3.546 + portion of the work they intended to do. This also affects 3.547 + how you work with project history. If you want to see all of 3.548 + the modifications someone made as part of a task, you will 3.549 + need to manually inspect the descriptions and timestamps of 3.550 + the changes made to each file involved (if you even know what 3.551 + those files were).</para> 3.552 + 3.553 + <para id="x_b7">CVS has a muddled notion of tags and branches that I will 3.554 + not attempt to even describe. It does not support renaming of 3.555 + files or directories well, making it easy to corrupt a 3.556 + repository. It has almost no internal consistency checking 3.557 + capabilities, so it is usually not even possible to tell 3.558 + whether or how a repository is corrupt. I would not recommend 3.559 + CVS for any project, existing or new.</para> 3.560 + 3.561 + <para id="x_b8">Mercurial can import CVS revision history. However, there 3.562 + are a few caveats that apply; these are true of every other 3.563 + revision control tool's CVS importer, too. Due to CVS's lack 3.564 + of atomic changes and unversioned filesystem hierarchy, it is 3.565 + not possible to reconstruct CVS history completely accurately; 3.566 + some guesswork is involved, and renames will usually not show 3.567 + up. Because a lot of advanced CVS administration has to be 3.568 + done by hand and is hence error-prone, it's common for CVS 3.569 + importers to run into multiple problems with corrupted 3.570 + repositories (completely bogus revision timestamps and files 3.571 + that have remained locked for over a decade are just two of 3.572 + the less interesting problems I can recall from personal 3.573 + experience).</para> 3.574 + 3.575 + <para id="x_b9">Mercurial can import revision history from a CVS 3.576 + repository.</para> 3.577 + 3.578 + 3.579 + </sect2> 3.580 + <sect2> 3.581 + <title>Commercial tools</title> 3.582 + 3.583 + <para id="x_ba">Perforce has a centralised client/server architecture, 3.584 + with no client-side caching of any data. Unlike modern 3.585 + revision control tools, Perforce requires that a user run a 3.586 + command to inform the server about every file they intend to 3.587 + edit.</para> 3.588 + 3.589 + <para id="x_bb">The performance of Perforce is quite good for small teams, 3.590 + but it falls off rapidly as the number of users grows beyond a 3.591 + few dozen. Modestly large Perforce installations require the 3.592 + deployment of proxies to cope with the load their users 3.593 + generate.</para> 3.594 + 3.595 + 3.596 + </sect2> 3.597 + <sect2> 3.598 + <title>Choosing a revision control tool</title> 3.599 + 3.600 + <para id="x_bc">With the exception of CVS, all of the tools listed above 3.601 + have unique strengths that suit them to particular styles of 3.602 + work. There is no single revision control tool that is best 3.603 + in all situations.</para> 3.604 + 3.605 + <para id="x_bd">As an example, Subversion is a good choice for working 3.606 + with frequently edited binary files, due to its centralised 3.607 + nature and support for file locking.</para> 3.608 + 3.609 + <para id="x_be">I personally find Mercurial's properties of simplicity, 3.610 + performance, and good merge support to be a compelling 3.611 + combination that has served me well for several years.</para> 3.612 + 3.613 + 3.614 + </sect2> 3.615 + </sect1> 3.616 + <sect1> 3.617 + <title>Switching from another tool to Mercurial</title> 3.618 + 3.619 + <para id="x_bf">Mercurial is bundled with an extension named <literal 3.620 + role="hg-ext">convert</literal>, which can incrementally 3.621 + import revision history from several other revision control 3.622 + tools. By <quote>incremental</quote>, I mean that you can 3.623 + convert all of a project's history to date in one go, then rerun 3.624 + the conversion later to obtain new changes that happened after 3.625 + the initial conversion.</para> 3.626 + 3.627 + <para id="x_c0">The revision control tools supported by <literal 3.628 + role="hg-ext">convert</literal> are as follows:</para> 3.629 + <itemizedlist> 3.630 + <listitem><para id="x_c1">Subversion</para></listitem> 3.631 + <listitem><para id="x_c2">CVS</para></listitem> 3.632 + <listitem><para id="x_c3">Git</para></listitem> 3.633 + <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist> 3.634 + 3.635 + <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can 3.636 + export changes from Mercurial to Subversion. This makes it 3.637 + possible to try Subversion and Mercurial in parallel before 3.638 + committing to a switchover, without risking the loss of any 3.639 + work.</para> 3.640 + 3.641 + <para id="x_c6">The <command role="hg-ext-convert">convert</command> command 3.642 + is easy to use. Simply point it at the path or URL of the 3.643 + source repository, optionally give it the name of the 3.644 + destination repository, and it will start working. After the 3.645 + initial conversion, just run the same command again to import 3.646 + new changes.</para> 3.647 + </sect1> 3.648 + 3.649 + <sect1> 3.650 + <title>A short history of revision control</title> 3.651 + 3.652 + <para id="x_c7">The best known of the old-time revision control tools is 3.653 + SCCS (Source Code Control System), which Marc Rochkind wrote at 3.654 + Bell Labs, in the early 1970s. SCCS operated on individual 3.655 + files, and required every person working on a project to have 3.656 + access to a shared workspace on a single system. Only one 3.657 + person could modify a file at any time; arbitration for access 3.658 + to files was via locks. It was common for people to lock files, 3.659 + and later forget to unlock them, preventing anyone else from 3.660 + modifying those files without the help of an 3.661 + administrator.</para> 3.662 + 3.663 + <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the 3.664 + early 1980s; he called his program RCS (Revision Control System). 3.665 + Like SCCS, RCS required developers to work in a single shared 3.666 + workspace, and to lock files to prevent multiple people from 3.667 + modifying them simultaneously.</para> 3.668 + 3.669 + <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block 3.670 + for a set of shell scripts he initially called cmt, but then 3.671 + renamed to CVS (Concurrent Versions System). The big innovation 3.672 + of CVS was that it let developers work simultaneously and 3.673 + somewhat independently in their own personal workspaces. The 3.674 + personal workspaces prevented developers from stepping on each 3.675 + other's toes all the time, as was common with SCCS and RCS. Each 3.676 + developer had a copy of every project file, and could modify 3.677 + their copies independently. They had to merge their edits prior 3.678 + to committing changes to the central repository.</para> 3.679 + 3.680 + <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote 3.681 + them in C, releasing in 1989 the code that has since developed 3.682 + into the modern version of CVS. CVS subsequently acquired the 3.683 + ability to operate over a network connection, giving it a 3.684 + client/server architecture. CVS's architecture is centralised; 3.685 + only the server has a copy of the history of the project. Client 3.686 + workspaces just contain copies of recent versions of the 3.687 + project's files, and a little metadata to tell them where the 3.688 + server is. CVS has been enormously successful; it is probably 3.689 + the world's most widely used revision control system.</para> 3.690 + 3.691 + <para id="x_cb">In the early 1990s, Sun Microsystems developed an early 3.692 + distributed revision control system, called TeamWare. A 3.693 + TeamWare workspace contains a complete copy of the project's 3.694 + history. TeamWare has no notion of a central repository. (CVS 3.695 + relied upon RCS for its history storage; TeamWare used 3.696 + SCCS.)</para> 3.697 + 3.698 + <para id="x_cc">As the 1990s progressed, awareness grew of a number of 3.699 + problems with CVS. It records simultaneous changes to multiple 3.700 + files individually, instead of grouping them together as a 3.701 + single logically atomic operation. It does not manage its file 3.702 + hierarchy well; it is easy to make a mess of a repository by 3.703 + renaming files and directories. Worse, its source code is 3.704 + difficult to read and maintain, which made the <quote>pain 3.705 + level</quote> of fixing these architectural problems 3.706 + prohibitive.</para> 3.707 + 3.708 + <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had 3.709 + worked on CVS, started a project to replace it with a tool that 3.710 + would have a better architecture and cleaner code. The result, 3.711 + Subversion, does not stray from CVS's centralised client/server 3.712 + model, but it adds multi-file atomic commits, better namespace 3.713 + management, and a number of other features that make it a 3.714 + generally better tool than CVS. Since its initial release, it 3.715 + has rapidly grown in popularity.</para> 3.716 + 3.717 + <para id="x_ce">More or less simultaneously, Graydon Hoare began working on 3.718 + an ambitious distributed revision control system that he named 3.719 + Monotone. While Monotone addresses many of CVS's design flaws 3.720 + and has a peer-to-peer architecture, it goes beyond earlier (and 3.721 + subsequent) revision control tools in a number of innovative 3.722 + ways. It uses cryptographic hashes as identifiers, and has an 3.723 + integral notion of <quote>trust</quote> for code from different 3.724 + sources.</para> 3.725 + 3.726 + <para id="x_cf">Mercurial began life in 2005. While a few aspects of its 3.727 + design are influenced by Monotone, Mercurial focuses on ease of 3.728 + use, high performance, and scalability to very large 3.729 + projects.</para> 3.730 + </sect1> 3.731 +</chapter> 3.732 + 3.733 +<!-- 3.734 +local variables: 3.735 +sgml-parent-document: ("00book.xml" "book" "chapter") 3.736 +end: 3.737 +-->
4.1 --- a/en/ch01-tour-basic.xml Thu May 07 21:06:49 2009 -0700 4.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 4.3 @@ -1,1035 +0,0 @@ 4.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 4.5 - 4.6 -<chapter id="chap:tour-basic"> 4.7 - <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?> 4.8 - <title>A tour of Mercurial: the basics</title> 4.9 - 4.10 - <sect1 id="sec:tour:install"> 4.11 - <title>Installing Mercurial on your system</title> 4.12 - 4.13 - <para id="x_1">Prebuilt binary packages of Mercurial are available for 4.14 - every popular operating system. These make it easy to start 4.15 - using Mercurial on your computer immediately.</para> 4.16 - 4.17 - <sect2> 4.18 - <title>Windows</title> 4.19 - 4.20 - <para id="x_c">The best version of Mercurial for Windows is 4.21 - TortoiseHg, which can be found at <ulink 4.22 - url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 4.23 - This package has no external dependencies; it <quote>just 4.24 - works</quote>. It provides both command line and graphical 4.25 - user interfaces.</para> 4.26 - 4.27 - </sect2> 4.28 - 4.29 - <sect2> 4.30 - <title>Mac OS X</title> 4.31 - 4.32 - <para id="x_a">Lee Cantey publishes an installer of Mercurial 4.33 - for Mac OS X at <ulink 4.34 - url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para> 4.35 - </sect2> 4.36 - 4.37 - <sect2> 4.38 - <title>Linux</title> 4.39 - 4.40 - <para id="x_2">Because each Linux distribution has its own packaging 4.41 - tools, policies, and rate of development, it's difficult to 4.42 - give a comprehensive set of instructions on how to install 4.43 - Mercurial binaries. The version of Mercurial that you will 4.44 - end up with can vary depending on how active the person is who 4.45 - maintains the package for your distribution.</para> 4.46 - 4.47 - <para id="x_3">To keep things simple, I will focus on installing 4.48 - Mercurial from the command line under the most popular Linux 4.49 - distributions. Most of these distributions provide graphical 4.50 - package managers that will let you install Mercurial with a 4.51 - single click; the package name to look for is 4.52 - <literal>mercurial</literal>.</para> 4.53 - 4.54 - <itemizedlist> 4.55 - <listitem><para id="x_4">Ubuntu and Debian:</para> 4.56 - <programlisting>apt-get install mercurial</programlisting></listitem> 4.57 - <listitem><para id="x_5">Fedora:</para> 4.58 - <programlisting>yum install mercurial</programlisting></listitem> 4.59 - <listitem><para id="x_715">OpenSUSE:</para> 4.60 - <programlisting>zypper install mercurial</programlisting></listitem> 4.61 - <listitem><para id="x_6">Gentoo:</para> 4.62 - <programlisting>emerge mercurial</programlisting></listitem> 4.63 - </itemizedlist> 4.64 - 4.65 - </sect2> 4.66 - <sect2> 4.67 - <title>Solaris</title> 4.68 - 4.69 - <para id="x_9">SunFreeWare, at <ulink 4.70 - url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 4.71 - provides prebuilt packages of Mercurial.</para> 4.72 - 4.73 - </sect2> 4.74 - 4.75 - </sect1> 4.76 - 4.77 - <sect1> 4.78 - <title>Getting started</title> 4.79 - 4.80 - <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg 4.81 - version</command> command to find out whether Mercurial is 4.82 - installed properly. The actual version information that it 4.83 - prints isn't so important; we simply care whether the command 4.84 - runs and prints anything at all.</para> 4.85 - 4.86 - &interaction.tour.version; 4.87 - 4.88 - <sect2> 4.89 - <title>Built-in help</title> 4.90 - 4.91 - <para id="x_f">Mercurial provides a built-in help system. This is 4.92 - invaluable for those times when you find yourself stuck 4.93 - trying to remember how to run a command. If you are 4.94 - completely stuck, simply run <command role="hg-cmd">hg 4.95 - help</command>; it will print a brief list of commands, 4.96 - along with a description of what each does. If you ask for 4.97 - help on a specific command (as below), it prints more 4.98 - detailed information.</para> 4.99 - 4.100 - &interaction.tour.help; 4.101 - 4.102 - <para id="x_10">For a more impressive level of detail (which you won't 4.103 - usually need) run <command role="hg-cmd">hg help <option 4.104 - role="hg-opt-global">-v</option></command>. The <option 4.105 - role="hg-opt-global">-v</option> option is short for 4.106 - <option role="hg-opt-global">--verbose</option>, and tells 4.107 - Mercurial to print more information than it usually 4.108 - would.</para> 4.109 - 4.110 - </sect2> 4.111 - </sect1> 4.112 - <sect1> 4.113 - <title>Working with a repository</title> 4.114 - 4.115 - <para id="x_11">In Mercurial, everything happens inside a 4.116 - <emphasis>repository</emphasis>. The repository for a project 4.117 - contains all of the files that <quote>belong to</quote> that 4.118 - project, along with a historical record of the project's 4.119 - files.</para> 4.120 - 4.121 - <para id="x_12">There's nothing particularly magical about a repository; it 4.122 - is simply a directory tree in your filesystem that Mercurial 4.123 - treats as special. You can rename or delete a repository any 4.124 - time you like, using either the command line or your file 4.125 - browser.</para> 4.126 - 4.127 - <sect2> 4.128 - <title>Making a local copy of a repository</title> 4.129 - 4.130 - <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little 4.131 - bit special. While you could use a normal file copying 4.132 - command to make a copy of a repository, it's best to use a 4.133 - built-in command that Mercurial provides. This command is 4.134 - called <command role="hg-cmd">hg clone</command>, because it 4.135 - makes an identical copy of an existing repository.</para> 4.136 - 4.137 - &interaction.tour.clone; 4.138 - 4.139 - <para id="x_67c">One advantage of using <command role="hg-cmd">hg 4.140 - clone</command> is that, as we can see above, it lets us clone 4.141 - repositories over the network. Another is that it remembers 4.142 - where we cloned from, which we'll find useful soon when we 4.143 - want to fetch new changes from another repository.</para> 4.144 - 4.145 - <para id="x_14">If our clone succeeded, we should now have a local 4.146 - directory called <filename class="directory">hello</filename>. 4.147 - This directory will contain some files.</para> 4.148 - 4.149 - &interaction.tour.ls; 4.150 - 4.151 - <para id="x_15">These files have the same contents and history in our 4.152 - repository as they do in the repository we cloned.</para> 4.153 - 4.154 - <para id="x_16">Every Mercurial repository is complete, 4.155 - self-contained, and independent. It contains its own private 4.156 - copy of a project's files and history. As we just mentioned, 4.157 - a cloned repository remembers the location of the repository 4.158 - it was cloned from, but Mercurial will not communicate with 4.159 - that repository, or any other, unless you tell it to.</para> 4.160 - 4.161 - <para id="x_17">What this means for now is that we're free to experiment 4.162 - with our repository, safe in the knowledge that it's a private 4.163 - <quote>sandbox</quote> that won't affect anyone else.</para> 4.164 - 4.165 - </sect2> 4.166 - <sect2> 4.167 - <title>What's in a repository?</title> 4.168 - 4.169 - <para id="x_18">When we take a more detailed look inside a repository, we 4.170 - can see that it contains a directory named <filename 4.171 - class="directory">.hg</filename>. This is where Mercurial 4.172 - keeps all of its metadata for the repository.</para> 4.173 - 4.174 - &interaction.tour.ls-a; 4.175 - 4.176 - <para id="x_19">The contents of the <filename 4.177 - class="directory">.hg</filename> directory and its 4.178 - subdirectories are private to Mercurial. Every other file and 4.179 - directory in the repository is yours to do with as you 4.180 - please.</para> 4.181 - 4.182 - <para id="x_1a">To introduce a little terminology, the <filename 4.183 - class="directory">.hg</filename> directory is the 4.184 - <quote>real</quote> repository, and all of the files and 4.185 - directories that coexist with it are said to live in the 4.186 - <emphasis>working directory</emphasis>. An easy way to 4.187 - remember the distinction is that the 4.188 - <emphasis>repository</emphasis> contains the 4.189 - <emphasis>history</emphasis> of your project, while the 4.190 - <emphasis>working directory</emphasis> contains a 4.191 - <emphasis>snapshot</emphasis> of your project at a particular 4.192 - point in history.</para> 4.193 - 4.194 - </sect2> 4.195 - </sect1> 4.196 - <sect1> 4.197 - <title>A tour through history</title> 4.198 - 4.199 - <para id="x_1b">One of the first things we might want to do with a new, 4.200 - unfamiliar repository is understand its history. The <command 4.201 - role="hg-cmd">hg log</command> command gives us a view of 4.202 - the history of changes in the repository.</para> 4.203 - 4.204 - &interaction.tour.log; 4.205 - 4.206 - <para id="x_1c">By default, this command prints a brief paragraph of output 4.207 - for each change to the project that was recorded. In Mercurial 4.208 - terminology, we call each of these recorded events a 4.209 - <emphasis>changeset</emphasis>, because it can contain a record 4.210 - of changes to several files.</para> 4.211 - 4.212 - <para id="x_1d">The fields in a record of output from <command 4.213 - role="hg-cmd">hg log</command> are as follows.</para> 4.214 - 4.215 - <itemizedlist> 4.216 - <listitem><para id="x_1e"><literal>changeset</literal>: This 4.217 - field has the format of a number, followed by a colon, 4.218 - followed by a hexadecimal (or <emphasis>hex</emphasis>) 4.219 - string. These are <emphasis>identifiers</emphasis> for the 4.220 - changeset. The hex string is a unique identifier: the same 4.221 - hex string will always refer to the same changeset in every 4.222 - copy of this repository. The 4.223 - number is shorter and easier to type than the hex string, 4.224 - but it isn't unique: the same number in two different clones 4.225 - of a repository may identify different changesets.</para> 4.226 - </listitem> 4.227 - <listitem><para id="x_1f"><literal>user</literal>: The identity of the 4.228 - person who created the changeset. This is a free-form 4.229 - field, but it most often contains a person's name and email 4.230 - address.</para></listitem> 4.231 - <listitem><para id="x_20"><literal>date</literal>: The date and time on 4.232 - which the changeset was created, and the timezone in which 4.233 - it was created. (The date and time are local to that 4.234 - timezone; they display what time and date it was for the 4.235 - person who created the changeset.)</para></listitem> 4.236 - <listitem><para id="x_21"><literal>summary</literal>: The first line of 4.237 - the text message that the creator of the changeset entered 4.238 - to describe the changeset.</para></listitem> 4.239 - <listitem> 4.240 - <para id="x_67d">Some changesets, such as the first in the list above, 4.241 - have a <literal>tag</literal> field. A tag is another way 4.242 - to identify a changeset, by giving it an easy-to-remember 4.243 - name. (The tag named <literal>tip</literal> is special: it 4.244 - always refers to the newest change in a repository.)</para> 4.245 - </listitem> 4.246 - </itemizedlist> 4.247 - 4.248 - <para id="x_22">The default output printed by <command 4.249 - role="hg-cmd">hg log</command> is purely a summary; it is 4.250 - missing a lot of detail.</para> 4.251 - 4.252 - <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides 4.253 - a graphical representation of the history of the <filename 4.254 - class="directory">hello</filename> repository, to make it a 4.255 - little easier to see which direction history is 4.256 - <quote>flowing</quote> in. We'll be returning to this figure 4.257 - several times in this chapter and the chapter that 4.258 - follows.</para> 4.259 - 4.260 - <figure id="fig:tour-basic:history"> 4.261 - <title>Graphical history of the <filename 4.262 - class="directory">hello</filename> repository</title> 4.263 - <mediaobject> 4.264 - <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject> 4.265 - <textobject><phrase>XXX add text</phrase></textobject> 4.266 - </mediaobject> 4.267 - </figure> 4.268 - 4.269 - <sect2> 4.270 - <title>Changesets, revisions, and talking to other 4.271 - people</title> 4.272 - 4.273 - <para id="x_25">As English is a notoriously sloppy language, and computer 4.274 - science has a hallowed history of terminological confusion 4.275 - (why use one term when four will do?), revision control has a 4.276 - variety of words and phrases that mean the same thing. If you 4.277 - are talking about Mercurial history with other people, you 4.278 - will find that the word <quote>changeset</quote> is often 4.279 - compressed to <quote>change</quote> or (when written) 4.280 - <quote>cset</quote>, and sometimes a changeset is referred to 4.281 - as a <quote>revision</quote> or a <quote>rev</quote>.</para> 4.282 - 4.283 - <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you 4.284 - use to refer to the concept of <quote>a changeset</quote>, the 4.285 - <emphasis>identifier</emphasis> that you use to refer to 4.286 - <quote>a <emphasis>specific</emphasis> changeset</quote> is of 4.287 - great importance. Recall that the <literal>changeset</literal> 4.288 - field in the output from <command role="hg-cmd">hg 4.289 - log</command> identifies a changeset using both a number and 4.290 - a hexadecimal string.</para> 4.291 - <itemizedlist> 4.292 - <listitem><para id="x_27">The revision number is a handy 4.293 - notation that is <emphasis>only valid in that 4.294 - repository</emphasis>.</para></listitem> 4.295 - <listitem><para id="x_28">The hexadecimal string is the 4.296 - <emphasis>permanent, unchanging identifier</emphasis> that 4.297 - will always identify that exact changeset in 4.298 - <emphasis>every</emphasis> copy of the 4.299 - repository.</para></listitem></itemizedlist> 4.300 - 4.301 - <para id="x_29">This distinction is important. If you send 4.302 - someone an email talking about <quote>revision 33</quote>, 4.303 - there's a high likelihood that their revision 33 will 4.304 - <emphasis>not be the same</emphasis> as yours. The reason for 4.305 - this is that a revision number depends on the order in which 4.306 - changes arrived in a repository, and there is no guarantee 4.307 - that the same changes will happen in the same order in 4.308 - different repositories. Three changes <literal>a,b,c</literal> 4.309 - can easily appear in one repository as 4.310 - <literal>0,1,2</literal>, while in another as 4.311 - <literal>0,2,1</literal>.</para> 4.312 - 4.313 - <para id="x_2a">Mercurial uses revision numbers purely as a convenient 4.314 - shorthand. If you need to discuss a changeset with someone, 4.315 - or make a record of a changeset for some other reason (for 4.316 - example, in a bug report), use the hexadecimal 4.317 - identifier.</para> 4.318 - 4.319 - </sect2> 4.320 - <sect2> 4.321 - <title>Viewing specific revisions</title> 4.322 - 4.323 - <para id="x_2b">To narrow the output of <command role="hg-cmd">hg 4.324 - log</command> down to a single revision, use the <option 4.325 - role="hg-opt-log">-r</option> (or <option 4.326 - role="hg-opt-log">--rev</option>) option. You can use 4.327 - either a revision number or a hexadecimal identifier, 4.328 - and you can provide as many revisions as you want.</para> 4.329 - 4.330 - &interaction.tour.log-r; 4.331 - 4.332 - <para id="x_2c">If you want to see the history of several revisions 4.333 - without having to list each one, you can use <emphasis>range 4.334 - notation</emphasis>; this lets you express the idea <quote>I 4.335 - want all revisions between <literal>abc</literal> and 4.336 - <literal>def</literal>, inclusive</quote>.</para> 4.337 - 4.338 - &interaction.tour.log.range; 4.339 - 4.340 - <para id="x_2d">Mercurial also honours the order in which you specify 4.341 - revisions, so <command role="hg-cmd">hg log -r 2:4</command> 4.342 - prints 2, 3, and 4. while <command role="hg-cmd">hg log -r 4.343 - 4:2</command> prints 4, 3, and 2.</para> 4.344 - 4.345 - </sect2> 4.346 - <sect2> 4.347 - <title>More detailed information</title> 4.348 - 4.349 - <para id="x_2e">While the summary information printed by <command 4.350 - role="hg-cmd">hg log</command> is useful if you already know 4.351 - what you're looking for, you may need to see a complete 4.352 - description of the change, or a list of the files changed, if 4.353 - you're trying to decide whether a changeset is the one you're 4.354 - looking for. The <command role="hg-cmd">hg log</command> 4.355 - command's <option role="hg-opt-global">-v</option> (or <option 4.356 - role="hg-opt-global">--verbose</option>) option gives you 4.357 - this extra detail.</para> 4.358 - 4.359 - &interaction.tour.log-v; 4.360 - 4.361 - <para id="x_2f">If you want to see both the description and 4.362 - content of a change, add the <option 4.363 - role="hg-opt-log">-p</option> (or <option 4.364 - role="hg-opt-log">--patch</option>) option. This displays 4.365 - the content of a change as a <emphasis>unified diff</emphasis> 4.366 - (if you've never seen a unified diff before, see <xref 4.367 - linkend="sec:mq:patch"/> for an overview).</para> 4.368 - 4.369 - &interaction.tour.log-vp; 4.370 - 4.371 - <para id="x_67e">The <option role="hg-opt-log">-p</option> option is 4.372 - tremendously useful, so it's well worth remembering.</para> 4.373 - 4.374 - </sect2> 4.375 - </sect1> 4.376 - 4.377 - <sect1> 4.378 - <title>All about command options</title> 4.379 - 4.380 - <para id="x_30">Let's take a brief break from exploring Mercurial commands 4.381 - to discuss a pattern in the way that they work; you may find 4.382 - this useful to keep in mind as we continue our tour.</para> 4.383 - 4.384 - <para id="x_31">Mercurial has a consistent and straightforward approach to 4.385 - dealing with the options that you can pass to commands. It 4.386 - follows the conventions for options that are common to modern 4.387 - Linux and Unix systems.</para> 4.388 - 4.389 - <itemizedlist> 4.390 - <listitem> 4.391 - <para id="x_32">Every option has a long name. For example, as 4.392 - we've already seen, the <command role="hg-cmd">hg 4.393 - log</command> command accepts a <option 4.394 - role="hg-opt-log">--rev</option> option.</para> 4.395 - </listitem> 4.396 - <listitem> 4.397 - <para id="x_33">Most options have short names, too. Instead 4.398 - of <option role="hg-opt-log">--rev</option>, we can use 4.399 - <option role="hg-opt-log">-r</option>. (The reason that 4.400 - some options don't have short names is that the options in 4.401 - question are rarely used.)</para> 4.402 - </listitem> 4.403 - <listitem> 4.404 - <para id="x_34">Long options start with two dashes (e.g. 4.405 - <option role="hg-opt-log">--rev</option>), while short 4.406 - options start with one (e.g. <option 4.407 - role="hg-opt-log">-r</option>).</para> 4.408 - </listitem> 4.409 - <listitem> 4.410 - <para id="x_35">Option naming and usage is consistent across 4.411 - commands. For example, every command that lets you specify 4.412 - a changeset ID or revision number accepts both <option 4.413 - role="hg-opt-log">-r</option> and <option 4.414 - role="hg-opt-log">--rev</option> arguments.</para> 4.415 - </listitem> 4.416 - <listitem> 4.417 - <para id="x_67f">If you are using short options, you can save typing by 4.418 - running them together. For example, the command <command 4.419 - role="hg-cmd">hg log -v -p -r 2</command> can be written 4.420 - as <command role="hg-cmd">hg log -vpr2</command>.</para> 4.421 - </listitem> 4.422 - </itemizedlist> 4.423 - 4.424 - <para id="x_36">In the examples throughout this book, I usually 4.425 - use short options instead of long. This simply reflects my own 4.426 - preference, so don't read anything significant into it.</para> 4.427 - 4.428 - <para id="x_37">Most commands that print output of some kind will print more 4.429 - output when passed a <option role="hg-opt-global">-v</option> 4.430 - (or <option role="hg-opt-global">--verbose</option>) option, and 4.431 - less when passed <option role="hg-opt-global">-q</option> (or 4.432 - <option role="hg-opt-global">--quiet</option>).</para> 4.433 - 4.434 - <note> 4.435 - <title>Option naming consistency</title> 4.436 - 4.437 - <para id="x_680">Almost always, Mercurial commands use consistent option 4.438 - names to refer to the same concepts. For instance, if a 4.439 - command deals with changesets, you'll always identify them 4.440 - with <option role="hg-opt-log">--rev</option> or <option 4.441 - role="hg-opt-log">-r</option>. This consistent use of 4.442 - option names makes it easier to remember what options a 4.443 - particular command takes.</para> 4.444 - </note> 4.445 - 4.446 - </sect1> 4.447 - <sect1> 4.448 - <title>Making and reviewing changes</title> 4.449 - 4.450 - <para id="x_38">Now that we have a grasp of viewing history in Mercurial, 4.451 - let's take a look at making some changes and examining 4.452 - them.</para> 4.453 - 4.454 - <para id="x_39">The first thing we'll do is isolate our experiment in a 4.455 - repository of its own. We use the <command role="hg-cmd">hg 4.456 - clone</command> command, but we don't need to clone a copy of 4.457 - the remote repository. Since we already have a copy of it 4.458 - locally, we can just clone that instead. This is much faster 4.459 - than cloning over the network, and cloning a local repository 4.460 - uses less disk space in most cases, too<footnote> 4.461 - <para id="x_681">The saving of space arises when source and destination 4.462 - repositories are on the same filesystem, in which case 4.463 - Mercurial will use hardlinks to do copy-on-write sharing of 4.464 - its internal metadata. If that explanation meant nothing to 4.465 - you, don't worry: everything happens transparently and 4.466 - automatically, and you don't need to understand it.</para> 4.467 - </footnote>.</para> 4.468 - 4.469 - &interaction.tour.reclone; 4.470 - 4.471 - <para id="x_3a">As an aside, it's often good practice to keep a 4.472 - <quote>pristine</quote> copy of a remote repository around, 4.473 - which you can then make temporary clones of to create sandboxes 4.474 - for each task you want to work on. This lets you work on 4.475 - multiple tasks in parallel, each isolated from the others until 4.476 - it's complete and you're ready to integrate it back. Because 4.477 - local clones are so cheap, there's almost no overhead to cloning 4.478 - and destroying repositories whenever you want.</para> 4.479 - 4.480 - <para id="x_3b">In our <filename class="directory">my-hello</filename> 4.481 - repository, we have a file <filename>hello.c</filename> that 4.482 - contains the classic <quote>hello, world</quote> program.</para> 4.483 - 4.484 - &interaction.tour.cat1; 4.485 - 4.486 - <para id="x_682">Let's edit this file so that it prints a second line of 4.487 - output.</para> 4.488 - 4.489 - &interaction.tour.cat2; 4.490 - 4.491 - <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> 4.492 - command will tell us what Mercurial knows about the files in the 4.493 - repository.</para> 4.494 - 4.495 - &interaction.tour.status; 4.496 - 4.497 - <para id="x_3d">The <command role="hg-cmd">hg status</command> command 4.498 - prints no output for some files, but a line starting with 4.499 - <quote><literal>M</literal></quote> for 4.500 - <filename>hello.c</filename>. Unless you tell it to, <command 4.501 - role="hg-cmd">hg status</command> will not print any output 4.502 - for files that have not been modified.</para> 4.503 - 4.504 - <para id="x_3e">The <quote><literal>M</literal></quote> indicates that 4.505 - Mercurial has noticed that we modified 4.506 - <filename>hello.c</filename>. We didn't need to 4.507 - <emphasis>inform</emphasis> Mercurial that we were going to 4.508 - modify the file before we started, or that we had modified the 4.509 - file after we were done; it was able to figure this out 4.510 - itself.</para> 4.511 - 4.512 - <para id="x_3f">It's somewhat helpful to know that we've modified 4.513 - <filename>hello.c</filename>, but we might prefer to know 4.514 - exactly <emphasis>what</emphasis> changes we've made to it. To 4.515 - do this, we use the <command role="hg-cmd">hg diff</command> 4.516 - command.</para> 4.517 - 4.518 - &interaction.tour.diff; 4.519 - 4.520 - <tip> 4.521 - <title>Understanding patches</title> 4.522 - 4.523 - <para id="x_683">Remember to take a look at <xref 4.524 - linkend="sec:mq:patch"/> if you don't know how to read 4.525 - output above.</para> 4.526 - </tip> 4.527 - </sect1> 4.528 - <sect1> 4.529 - <title>Recording changes in a new changeset</title> 4.530 - 4.531 - <para id="x_40">We can modify files, build and test our changes, and use 4.532 - <command role="hg-cmd">hg status</command> and <command 4.533 - role="hg-cmd">hg diff</command> to review our changes, until 4.534 - we're satisfied with what we've done and arrive at a natural 4.535 - stopping point where we want to record our work in a new 4.536 - changeset.</para> 4.537 - 4.538 - <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets 4.539 - us create a new changeset; we'll usually refer to this as 4.540 - <quote>making a commit</quote> or 4.541 - <quote>committing</quote>.</para> 4.542 - 4.543 - <sect2> 4.544 - <title>Setting up a username</title> 4.545 - 4.546 - <para id="x_42">When you try to run <command role="hg-cmd">hg 4.547 - commit</command> for the first time, it is not guaranteed to 4.548 - succeed. Mercurial records your name and address with each 4.549 - change that you commit, so that you and others will later be 4.550 - able to tell who made each change. Mercurial tries to 4.551 - automatically figure out a sensible username to commit the 4.552 - change with. It will attempt each of the following methods, 4.553 - in order:</para> 4.554 - <orderedlist> 4.555 - <listitem><para id="x_43">If you specify a <option 4.556 - role="hg-opt-commit">-u</option> option to the <command 4.557 - role="hg-cmd">hg commit</command> command on the command 4.558 - line, followed by a username, this is always given the 4.559 - highest precedence.</para></listitem> 4.560 - <listitem><para id="x_44">If you have set the <envar>HGUSER</envar> 4.561 - environment variable, this is checked 4.562 - next.</para></listitem> 4.563 - <listitem><para id="x_45">If you create a file in your home 4.564 - directory called <filename 4.565 - role="special">.hgrc</filename>, with a <envar 4.566 - role="rc-item-ui">username</envar> entry, that will be 4.567 - used next. To see what the contents of this file should 4.568 - look like, refer to <xref 4.569 - linkend="sec:tour-basic:username"/> 4.570 - below.</para></listitem> 4.571 - <listitem><para id="x_46">If you have set the <envar>EMAIL</envar> 4.572 - environment variable, this will be used 4.573 - next.</para></listitem> 4.574 - <listitem><para id="x_47">Mercurial will query your system to find out 4.575 - your local user name and host name, and construct a 4.576 - username from these components. Since this often results 4.577 - in a username that is not very useful, it will print a 4.578 - warning if it has to do 4.579 - this.</para></listitem> 4.580 - </orderedlist> 4.581 - <para id="x_48">If all of these mechanisms fail, Mercurial will 4.582 - fail, printing an error message. In this case, it will not 4.583 - let you commit until you set up a 4.584 - username.</para> 4.585 - <para id="x_49">You should think of the <envar>HGUSER</envar> environment 4.586 - variable and the <option role="hg-opt-commit">-u</option> 4.587 - option to the <command role="hg-cmd">hg commit</command> 4.588 - command as ways to <emphasis>override</emphasis> Mercurial's 4.589 - default selection of username. For normal use, the simplest 4.590 - and most robust way to set a username for yourself is by 4.591 - creating a <filename role="special">.hgrc</filename> file; see 4.592 - below for details.</para> 4.593 - <sect3 id="sec:tour-basic:username"> 4.594 - <title>Creating a Mercurial configuration file</title> 4.595 - 4.596 - <para id="x_4a">To set a user name, use your favorite editor 4.597 - to create a file called <filename 4.598 - role="special">.hgrc</filename> in your home directory. 4.599 - Mercurial will use this file to look up your personalised 4.600 - configuration settings. The initial contents of your 4.601 - <filename role="special">.hgrc</filename> should look like 4.602 - this.</para> 4.603 - 4.604 - <tip> 4.605 - <title><quote>Home directory</quote> on Windows</title> 4.606 - 4.607 - <para id="x_716">When we refer to your home directory, on an English 4.608 - language installation of Windows this will usually be a 4.609 - folder named after your user name in 4.610 - <filename>C:\Documents and Settings</filename>. You can 4.611 - find out the exact name of your home directory by opening 4.612 - a command prompt window and running the following 4.613 - command.</para> 4.614 - 4.615 - <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen> 4.616 - </tip> 4.617 - 4.618 - <programlisting># This is a Mercurial configuration file. 4.619 -[ui] 4.620 -username = Firstname Lastname <email.address@example.net></programlisting> 4.621 - 4.622 - <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a 4.623 - <emphasis>section</emphasis> of the config file, so you can 4.624 - read the <quote><literal>username = ...</literal></quote> 4.625 - line as meaning <quote>set the value of the 4.626 - <literal>username</literal> item in the 4.627 - <literal>ui</literal> section</quote>. A section continues 4.628 - until a new section begins, or the end of the file. 4.629 - Mercurial ignores empty lines and treats any text from 4.630 - <quote><literal>#</literal></quote> to the end of a line as 4.631 - a comment.</para> 4.632 - </sect3> 4.633 - 4.634 - <sect3> 4.635 - <title>Choosing a user name</title> 4.636 - 4.637 - <para id="x_4c">You can use any text you like as the value of 4.638 - the <literal>username</literal> config item, since this 4.639 - information is for reading by other people, but will not be 4.640 - interpreted by Mercurial. The convention that most people 4.641 - follow is to use their name and email address, as in the 4.642 - example above.</para> 4.643 - <note> 4.644 - <para id="x_4d">Mercurial's built-in web server obfuscates 4.645 - email addresses, to make it more difficult for the email 4.646 - harvesting tools that spammers use. This reduces the 4.647 - likelihood that you'll start receiving more junk email if 4.648 - you publish a Mercurial repository on the 4.649 - web.</para></note> 4.650 - </sect3> 4.651 - </sect2> 4.652 - <sect2> 4.653 - <title>Writing a commit message</title> 4.654 - 4.655 - <para id="x_4e">When we commit a change, Mercurial drops us into 4.656 - a text editor, to enter a message that will describe the 4.657 - modifications we've made in this changeset. This is called 4.658 - the <emphasis>commit message</emphasis>. It will be a record 4.659 - for readers of what we did and why, and it will be printed by 4.660 - <command role="hg-cmd">hg log</command> after we've finished 4.661 - committing.</para> 4.662 - 4.663 - &interaction.tour.commit; 4.664 - 4.665 - <para id="x_4f">The editor that the <command role="hg-cmd">hg 4.666 - commit</command> command drops us into will contain an empty 4.667 - line or two, followed by a number of lines starting with 4.668 - <quote><literal>HG:</literal></quote>.</para> 4.669 - 4.670 - <programlisting> 4.671 -This is where I type my commit comment. 4.672 - 4.673 -HG: Enter commit message. Lines beginning with 'HG:' are removed. 4.674 -HG: -- 4.675 -HG: user: Bryan O'Sullivan <bos@serpentine.com> 4.676 -HG: branch 'default' 4.677 -HG: changed hello.c</programlisting> 4.678 - 4.679 - <para id="x_50">Mercurial ignores the lines that start with 4.680 - <quote><literal>HG:</literal></quote>; it uses them only to 4.681 - tell us which files it's recording changes to. Modifying or 4.682 - deleting these lines has no effect.</para> 4.683 - </sect2> 4.684 - <sect2> 4.685 - <title>Writing a good commit message</title> 4.686 - 4.687 - <para id="x_51">Since <command role="hg-cmd">hg log</command> 4.688 - only prints the first line of a commit message by default, 4.689 - it's best to write a commit message whose first line stands 4.690 - alone. Here's a real example of a commit message that 4.691 - <emphasis>doesn't</emphasis> follow this guideline, and hence 4.692 - has a summary that is not readable.</para> 4.693 - 4.694 - <programlisting> 4.695 -changeset: 73:584af0e231be 4.696 -user: Censored Person <censored.person@example.org> 4.697 -date: Tue Sep 26 21:37:07 2006 -0700 4.698 -summary: include buildmeister/commondefs. Add exports.</programlisting> 4.699 - 4.700 - <para id="x_52">As far as the remainder of the contents of the 4.701 - commit message are concerned, there are no hard-and-fast 4.702 - rules. Mercurial itself doesn't interpret or care about the 4.703 - contents of the commit message, though your project may have 4.704 - policies that dictate a certain kind of formatting.</para> 4.705 - <para id="x_53">My personal preference is for short, but 4.706 - informative, commit messages that tell me something that I 4.707 - can't figure out with a quick glance at the output of <command 4.708 - role="hg-cmd">hg log --patch</command>.</para> 4.709 - <para id="x_55">If we run the <command role="hg-cmd">hg 4.710 - commit</command> command without any arguments, it records 4.711 - all of the changes we've made, as reported by <command 4.712 - role="hg-cmd">hg status</command> and <command 4.713 - role="hg-cmd">hg diff</command>.</para> 4.714 - 4.715 - <note> 4.716 - <title>A surprise for Subversion users</title> 4.717 - 4.718 - <para id="x_717">Like other Mercurial commands, if we don't supply 4.719 - explicit names to commit to the <command role="hg-cmd">hg 4.720 - commit</command>, it will operate across a repository's 4.721 - entire working directory. Be wary of this if you're coming 4.722 - from the Subversion or CVS world, since you might expect it 4.723 - to operate only on the current directory that you happen to 4.724 - be visiting and its subdirectories.</para> 4.725 - </note> 4.726 - </sect2> 4.727 - 4.728 - <sect2> 4.729 - <title>Aborting a commit</title> 4.730 - 4.731 - <para id="x_54">If you decide that you don't want to commit 4.732 - while in the middle of editing a commit message, simply exit 4.733 - from your editor without saving the file that it's editing. 4.734 - This will cause nothing to happen to either the repository or 4.735 - the working directory.</para> 4.736 - </sect2> 4.737 - 4.738 - <sect2> 4.739 - <title>Admiring our new handiwork</title> 4.740 - 4.741 - <para id="x_56">Once we've finished the commit, we can use the 4.742 - <command role="hg-cmd">hg tip</command> command to display the 4.743 - changeset we just created. This command produces output that 4.744 - is identical to <command role="hg-cmd">hg log</command>, but 4.745 - it only displays the newest revision in the repository.</para> 4.746 - 4.747 - &interaction.tour.tip; 4.748 - 4.749 - <para id="x_57">We refer to the newest revision in the 4.750 - repository as the <emphasis>tip revision</emphasis>, or simply 4.751 - the <emphasis>tip</emphasis>.</para> 4.752 - 4.753 - <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command> 4.754 - command accepts many of the same options as <command 4.755 - role="hg-cmd">hg log</command>, so <option 4.756 - role="hg-opt-global">-v</option> above indicates <quote>be 4.757 - verbose</quote>, <option role="hg-opt-tip">-p</option> 4.758 - specifies <quote>print a patch</quote>. The use of <option 4.759 - role="hg-opt-tip">-p</option> to print patches is another 4.760 - example of the consistent naming we mentioned earlier.</para> 4.761 - </sect2> 4.762 - </sect1> 4.763 - 4.764 - <sect1> 4.765 - <title>Sharing changes</title> 4.766 - 4.767 - <para id="x_58">We mentioned earlier that repositories in 4.768 - Mercurial are self-contained. This means that the changeset we 4.769 - just created exists only in our <filename 4.770 - class="directory">my-hello</filename> repository. Let's look 4.771 - at a few ways that we can propagate this change into other 4.772 - repositories.</para> 4.773 - 4.774 - <sect2 id="sec:tour:pull"> 4.775 - <title>Pulling changes from another repository</title> 4.776 - 4.777 - <para id="x_59">To get started, let's clone our original 4.778 - <filename class="directory">hello</filename> repository, which 4.779 - does not contain the change we just committed. We'll call our 4.780 - temporary repository <filename 4.781 - class="directory">hello-pull</filename>.</para> 4.782 - 4.783 - &interaction.tour.clone-pull; 4.784 - 4.785 - <para id="x_5a">We'll use the <command role="hg-cmd">hg 4.786 - pull</command> command to bring changes from <filename 4.787 - class="directory">my-hello</filename> into <filename 4.788 - class="directory">hello-pull</filename>. However, blindly 4.789 - pulling unknown changes into a repository is a somewhat scary 4.790 - prospect. Mercurial provides the <command role="hg-cmd">hg 4.791 - incoming</command> command to tell us what changes the 4.792 - <command role="hg-cmd">hg pull</command> command 4.793 - <emphasis>would</emphasis> pull into the repository, without 4.794 - actually pulling the changes in.</para> 4.795 - 4.796 - &interaction.tour.incoming; 4.797 - 4.798 - <para id="x_5c">Bringing changes into a repository is a simple 4.799 - matter of running the <command role="hg-cmd">hg pull</command> 4.800 - command, and optionally telling it which repository to pull from.</para> 4.801 - 4.802 - &interaction.tour.pull; 4.803 - 4.804 - <para id="x_5d">As you can see from the before-and-after output 4.805 - of <command role="hg-cmd">hg tip</command>, we have 4.806 - successfully pulled changes into our repository. However, 4.807 - Mercurial separates pulling changes in from updating the 4.808 - working directory. There remains one step before we will see 4.809 - the changes that we just pulled appear in the working 4.810 - directory.</para> 4.811 - 4.812 - <tip> 4.813 - <title>Pulling specific changes</title> 4.814 - 4.815 - <para id="x_5b">It is possible that due to the delay between 4.816 - running <command role="hg-cmd">hg incoming</command> and 4.817 - <command role="hg-cmd">hg pull</command>, you may not see 4.818 - all changesets that will be brought from the other 4.819 - repository. Suppose you're pulling changes from a repository 4.820 - on the network somewhere. While you are looking at the 4.821 - <command role="hg-cmd">hg incoming</command> output, and 4.822 - before you pull those changes, someone might have committed 4.823 - something in the remote repository. This means that it's 4.824 - possible to pull more changes than you saw when using 4.825 - <command role="hg-cmd">hg incoming</command>.</para> 4.826 - 4.827 - <para id="x_718">If you only want to pull precisely the changes that were 4.828 - listed by <command role="hg-cmd">hg incoming</command>, or 4.829 - you have some other reason to pull a subset of changes, 4.830 - simply identify the change that you want to pull by its 4.831 - changeset ID, e.g. <command>hg pull 4.832 - -r7e95bb</command>.</para> 4.833 - </tip> 4.834 - </sect2> 4.835 - 4.836 - <sect2> 4.837 - <title>Updating the working directory</title> 4.838 - 4.839 - <para id="x_5e">We have so far glossed over the relationship 4.840 - between a repository and its working directory. The <command 4.841 - role="hg-cmd">hg pull</command> command that we ran in 4.842 - <xref linkend="sec:tour:pull"/> brought changes into the 4.843 - repository, but if we check, there's no sign of those changes 4.844 - in the working directory. This is because <command 4.845 - role="hg-cmd">hg pull</command> does not (by default) touch 4.846 - the working directory. Instead, we use the <command 4.847 - role="hg-cmd">hg update</command> command to do this.</para> 4.848 - 4.849 - &interaction.tour.update; 4.850 - 4.851 - <para id="x_5f">It might seem a bit strange that <command 4.852 - role="hg-cmd">hg pull</command> doesn't update the working 4.853 - directory automatically. There's actually a good reason for 4.854 - this: you can use <command role="hg-cmd">hg update</command> 4.855 - to update the working directory to the state it was in at 4.856 - <emphasis>any revision</emphasis> in the history of the 4.857 - repository. If you had the working directory updated to an 4.858 - old revision&emdash;to hunt down the origin of a bug, 4.859 - say&emdash;and ran a <command role="hg-cmd">hg pull</command> 4.860 - which automatically updated the working directory to a new 4.861 - revision, you might not be terribly happy.</para> 4.862 - 4.863 - <para id="x_60">Since pull-then-update is such a common sequence 4.864 - of operations, Mercurial lets you combine the two by passing 4.865 - the <option role="hg-opt-pull">-u</option> option to <command 4.866 - role="hg-cmd">hg pull</command>.</para> 4.867 - 4.868 - <para id="x_61">If you look back at the output of <command 4.869 - role="hg-cmd">hg pull</command> in <xref 4.870 - linkend="sec:tour:pull"/> when we ran it without <option 4.871 - role="hg-opt-pull">-u</option>, you can see that it printed 4.872 - a helpful reminder that we'd have to take an explicit step to 4.873 - update the working directory.</para> 4.874 - 4.875 - <para id="x_62">To find out what revision the working directory 4.876 - is at, use the <command role="hg-cmd">hg parents</command> 4.877 - command.</para> 4.878 - 4.879 - &interaction.tour.parents; 4.880 - 4.881 - <para id="x_63">If you look back at <xref 4.882 - linkend="fig:tour-basic:history"/>, you'll see arrows 4.883 - connecting each changeset. The node that the arrow leads 4.884 - <emphasis>from</emphasis> in each case is a parent, and the 4.885 - node that the arrow leads <emphasis>to</emphasis> is its 4.886 - child. The working directory has a parent in just the same 4.887 - way; this is the changeset that the working directory 4.888 - currently contains.</para> 4.889 - 4.890 - <para id="x_64">To update the working directory to a particular 4.891 - revision, give a revision number or changeset ID to the 4.892 - <command role="hg-cmd">hg update</command> command.</para> 4.893 - 4.894 - &interaction.tour.older; 4.895 - 4.896 - <para id="x_65">If you omit an explicit revision, <command 4.897 - role="hg-cmd">hg update</command> will update to the tip 4.898 - revision, as shown by the second call to <command 4.899 - role="hg-cmd">hg update</command> in the example 4.900 - above.</para> 4.901 - </sect2> 4.902 - 4.903 - <sect2> 4.904 - <title>Pushing changes to another repository</title> 4.905 - 4.906 - <para id="x_66">Mercurial lets us push changes to another 4.907 - repository, from the repository we're currently visiting. As 4.908 - with the example of <command role="hg-cmd">hg pull</command> 4.909 - above, we'll create a temporary repository to push our changes 4.910 - into.</para> 4.911 - 4.912 - &interaction.tour.clone-push; 4.913 - 4.914 - <para id="x_67">The <command role="hg-cmd">hg outgoing</command> 4.915 - command tells us what changes would be pushed into another 4.916 - repository.</para> 4.917 - 4.918 - &interaction.tour.outgoing; 4.919 - 4.920 - <para id="x_68">And the <command role="hg-cmd">hg push</command> 4.921 - command does the actual push.</para> 4.922 - 4.923 - &interaction.tour.push; 4.924 - 4.925 - <para id="x_69">As with <command role="hg-cmd">hg 4.926 - pull</command>, the <command role="hg-cmd">hg push</command> 4.927 - command does not update the working directory in the 4.928 - repository that it's pushing changes into. Unlike <command 4.929 - role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg 4.930 - push</command> does not provide a <literal>-u</literal> 4.931 - option that updates the other repository's working directory. 4.932 - This asymmetry is deliberate: the repository we're pushing to 4.933 - might be on a remote server and shared between several people. 4.934 - If we were to update its working directory while someone was 4.935 - working in it, their work would be disrupted.</para> 4.936 - 4.937 - <para id="x_6a">What happens if we try to pull or push changes 4.938 - and the receiving repository already has those changes? 4.939 - Nothing too exciting.</para> 4.940 - 4.941 - &interaction.tour.push.nothing; 4.942 - </sect2> 4.943 - 4.944 - <sect2> 4.945 - <title>Default locations</title> 4.946 - 4.947 - <para id="x_719">When we clone a repository, Mercurial records the location 4.948 - of the repository we cloned in the 4.949 - <filename>.hg/hgrc</filename> file of the new repository. If 4.950 - we don't supply a location to <command>hg pull</command> from 4.951 - or <command>hg push</command> to, those commands will use this 4.952 - location as a default. The <command>hg incoming</command> 4.953 - and <command>hg outgoing</command> commands do so too.</para> 4.954 - 4.955 - <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename> 4.956 - file in a text editor, you will see contents like the 4.957 - following.</para> 4.958 - 4.959 - <programlisting>[paths] 4.960 -default = http://www.selenic.com/repo/hg</programlisting> 4.961 - 4.962 - <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the 4.963 - default location for <command>hg push</command> and 4.964 - <command>hg outgoing</command> be different from those for 4.965 - <command>hg pull</command> and <command>hg incoming</command>. 4.966 - We can do this by adding a <literal>default-push</literal> 4.967 - entry to the <literal>[paths]</literal> section of the 4.968 - <filename>.hg/hgrc</filename> file, as follows.</para> 4.969 - 4.970 - <programlisting>[paths] 4.971 -default = http://www.selenic.com/repo/hg 4.972 -default-push = http://hg.example.com/hg</programlisting> 4.973 - </sect2> 4.974 - 4.975 - <sect2> 4.976 - <title>Sharing changes over a network</title> 4.977 - 4.978 - <para id="x_6b">The commands we have covered in the previous few 4.979 - sections are not limited to working with local repositories. 4.980 - Each works in exactly the same fashion over a network 4.981 - connection; simply pass in a URL instead of a local 4.982 - path.</para> 4.983 - 4.984 - &interaction.tour.outgoing.net; 4.985 - 4.986 - <para id="x_6c">In this example, we can see what changes we 4.987 - could push to the remote repository, but the repository is 4.988 - understandably not set up to let anonymous users push to 4.989 - it.</para> 4.990 - 4.991 - &interaction.tour.push.net; 4.992 - </sect2> 4.993 - </sect1> 4.994 - 4.995 - <sect1> 4.996 - <title>Starting a new project</title> 4.997 - 4.998 - <para id="x_71c">It is just as easy to begin a new project as to work on one 4.999 - that already exists. The <command>hg init</command> command 4.1000 - creates a new, empty Mercurial repository.</para> 4.1001 - 4.1002 - &interaction.ch01-new.init; 4.1003 - 4.1004 - <para id="x_71d">This simply creates a repository named 4.1005 - <filename>myproject</filename> in the current directory.</para> 4.1006 - 4.1007 - &interaction.ch01-new.ls; 4.1008 - 4.1009 - <para id="x_71e">We can tell that <filename>myproject</filename> is a 4.1010 - Mercurial repository, because it contains a 4.1011 - <filename>.hg</filename> directory.</para> 4.1012 - 4.1013 - &interaction.ch01-new.ls2; 4.1014 - 4.1015 - <para id="x_71f">If we want to add some pre-existing files to the repository, 4.1016 - we copy them into place, and tell Mercurial to start tracking 4.1017 - them using the <command>hg add</command> command.</para> 4.1018 - 4.1019 - &interaction.ch01-new.add; 4.1020 - 4.1021 - <para id="x_720">Once we are satisfied that our project looks right, we 4.1022 - commit our changes.</para> 4.1023 - 4.1024 - &interaction.ch01-new.commit; 4.1025 - 4.1026 - <para id="x_721">It takes just a few moments to start using Mercurial on a 4.1027 - new project, which is part of its appeal. Revision control is 4.1028 - now so easy to work with, we can use it on the smallest of 4.1029 - projects that we might not have considered with a more 4.1030 - complicated tool.</para> 4.1031 - </sect1> 4.1032 -</chapter> 4.1033 - 4.1034 -<!-- 4.1035 -local variables: 4.1036 -sgml-parent-document: ("00book.xml" "book" "chapter") 4.1037 -end: 4.1038 --->
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/ch02-tour-basic.xml Thu May 07 21:07:35 2009 -0700 5.3 @@ -0,0 +1,1035 @@ 5.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 5.5 + 5.6 +<chapter id="chap:tour-basic"> 5.7 + <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?> 5.8 + <title>A tour of Mercurial: the basics</title> 5.9 + 5.10 + <sect1 id="sec:tour:install"> 5.11 + <title>Installing Mercurial on your system</title> 5.12 + 5.13 + <para id="x_1">Prebuilt binary packages of Mercurial are available for 5.14 + every popular operating system. These make it easy to start 5.15 + using Mercurial on your computer immediately.</para> 5.16 + 5.17 + <sect2> 5.18 + <title>Windows</title> 5.19 + 5.20 + <para id="x_c">The best version of Mercurial for Windows is 5.21 + TortoiseHg, which can be found at <ulink 5.22 + url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 5.23 + This package has no external dependencies; it <quote>just 5.24 + works</quote>. It provides both command line and graphical 5.25 + user interfaces.</para> 5.26 + 5.27 + </sect2> 5.28 + 5.29 + <sect2> 5.30 + <title>Mac OS X</title> 5.31 + 5.32 + <para id="x_a">Lee Cantey publishes an installer of Mercurial 5.33 + for Mac OS X at <ulink 5.34 + url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para> 5.35 + </sect2> 5.36 + 5.37 + <sect2> 5.38 + <title>Linux</title> 5.39 + 5.40 + <para id="x_2">Because each Linux distribution has its own packaging 5.41 + tools, policies, and rate of development, it's difficult to 5.42 + give a comprehensive set of instructions on how to install 5.43 + Mercurial binaries. The version of Mercurial that you will 5.44 + end up with can vary depending on how active the person is who 5.45 + maintains the package for your distribution.</para> 5.46 + 5.47 + <para id="x_3">To keep things simple, I will focus on installing 5.48 + Mercurial from the command line under the most popular Linux 5.49 + distributions. Most of these distributions provide graphical 5.50 + package managers that will let you install Mercurial with a 5.51 + single click; the package name to look for is 5.52 + <literal>mercurial</literal>.</para> 5.53 + 5.54 + <itemizedlist> 5.55 + <listitem><para id="x_4">Ubuntu and Debian:</para> 5.56 + <programlisting>apt-get install mercurial</programlisting></listitem> 5.57 + <listitem><para id="x_5">Fedora:</para> 5.58 + <programlisting>yum install mercurial</programlisting></listitem> 5.59 + <listitem><para id="x_715">OpenSUSE:</para> 5.60 + <programlisting>zypper install mercurial</programlisting></listitem> 5.61 + <listitem><para id="x_6">Gentoo:</para> 5.62 + <programlisting>emerge mercurial</programlisting></listitem> 5.63 + </itemizedlist> 5.64 + 5.65 + </sect2> 5.66 + <sect2> 5.67 + <title>Solaris</title> 5.68 + 5.69 + <para id="x_9">SunFreeWare, at <ulink 5.70 + url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 5.71 + provides prebuilt packages of Mercurial.</para> 5.72 + 5.73 + </sect2> 5.74 + 5.75 + </sect1> 5.76 + 5.77 + <sect1> 5.78 + <title>Getting started</title> 5.79 + 5.80 + <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg 5.81 + version</command> command to find out whether Mercurial is 5.82 + installed properly. The actual version information that it 5.83 + prints isn't so important; we simply care whether the command 5.84 + runs and prints anything at all.</para> 5.85 + 5.86 + &interaction.tour.version; 5.87 + 5.88 + <sect2> 5.89 + <title>Built-in help</title> 5.90 + 5.91 + <para id="x_f">Mercurial provides a built-in help system. This is 5.92 + invaluable for those times when you find yourself stuck 5.93 + trying to remember how to run a command. If you are 5.94 + completely stuck, simply run <command role="hg-cmd">hg 5.95 + help</command>; it will print a brief list of commands, 5.96 + along with a description of what each does. If you ask for 5.97 + help on a specific command (as below), it prints more 5.98 + detailed information.</para> 5.99 + 5.100 + &interaction.tour.help; 5.101 + 5.102 + <para id="x_10">For a more impressive level of detail (which you won't 5.103 + usually need) run <command role="hg-cmd">hg help <option 5.104 + role="hg-opt-global">-v</option></command>. The <option 5.105 + role="hg-opt-global">-v</option> option is short for 5.106 + <option role="hg-opt-global">--verbose</option>, and tells 5.107 + Mercurial to print more information than it usually 5.108 + would.</para> 5.109 + 5.110 + </sect2> 5.111 + </sect1> 5.112 + <sect1> 5.113 + <title>Working with a repository</title> 5.114 + 5.115 + <para id="x_11">In Mercurial, everything happens inside a 5.116 + <emphasis>repository</emphasis>. The repository for a project 5.117 + contains all of the files that <quote>belong to</quote> that 5.118 + project, along with a historical record of the project's 5.119 + files.</para> 5.120 + 5.121 + <para id="x_12">There's nothing particularly magical about a repository; it 5.122 + is simply a directory tree in your filesystem that Mercurial 5.123 + treats as special. You can rename or delete a repository any 5.124 + time you like, using either the command line or your file 5.125 + browser.</para> 5.126 + 5.127 + <sect2> 5.128 + <title>Making a local copy of a repository</title> 5.129 + 5.130 + <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little 5.131 + bit special. While you could use a normal file copying 5.132 + command to make a copy of a repository, it's best to use a 5.133 + built-in command that Mercurial provides. This command is 5.134 + called <command role="hg-cmd">hg clone</command>, because it 5.135 + makes an identical copy of an existing repository.</para> 5.136 + 5.137 + &interaction.tour.clone; 5.138 + 5.139 + <para id="x_67c">One advantage of using <command role="hg-cmd">hg 5.140 + clone</command> is that, as we can see above, it lets us clone 5.141 + repositories over the network. Another is that it remembers 5.142 + where we cloned from, which we'll find useful soon when we 5.143 + want to fetch new changes from another repository.</para> 5.144 + 5.145 + <para id="x_14">If our clone succeeded, we should now have a local 5.146 + directory called <filename class="directory">hello</filename>. 5.147 + This directory will contain some files.</para> 5.148 + 5.149 + &interaction.tour.ls; 5.150 + 5.151 + <para id="x_15">These files have the same contents and history in our 5.152 + repository as they do in the repository we cloned.</para> 5.153 + 5.154 + <para id="x_16">Every Mercurial repository is complete, 5.155 + self-contained, and independent. It contains its own private 5.156 + copy of a project's files and history. As we just mentioned, 5.157 + a cloned repository remembers the location of the repository 5.158 + it was cloned from, but Mercurial will not communicate with 5.159 + that repository, or any other, unless you tell it to.</para> 5.160 + 5.161 + <para id="x_17">What this means for now is that we're free to experiment 5.162 + with our repository, safe in the knowledge that it's a private 5.163 + <quote>sandbox</quote> that won't affect anyone else.</para> 5.164 + 5.165 + </sect2> 5.166 + <sect2> 5.167 + <title>What's in a repository?</title> 5.168 + 5.169 + <para id="x_18">When we take a more detailed look inside a repository, we 5.170 + can see that it contains a directory named <filename 5.171 + class="directory">.hg</filename>. This is where Mercurial 5.172 + keeps all of its metadata for the repository.</para> 5.173 + 5.174 + &interaction.tour.ls-a; 5.175 + 5.176 + <para id="x_19">The contents of the <filename 5.177 + class="directory">.hg</filename> directory and its 5.178 + subdirectories are private to Mercurial. Every other file and 5.179 + directory in the repository is yours to do with as you 5.180 + please.</para> 5.181 + 5.182 + <para id="x_1a">To introduce a little terminology, the <filename 5.183 + class="directory">.hg</filename> directory is the 5.184 + <quote>real</quote> repository, and all of the files and 5.185 + directories that coexist with it are said to live in the 5.186 + <emphasis>working directory</emphasis>. An easy way to 5.187 + remember the distinction is that the 5.188 + <emphasis>repository</emphasis> contains the 5.189 + <emphasis>history</emphasis> of your project, while the 5.190 + <emphasis>working directory</emphasis> contains a 5.191 + <emphasis>snapshot</emphasis> of your project at a particular 5.192 + point in history.</para> 5.193 + 5.194 + </sect2> 5.195 + </sect1> 5.196 + <sect1> 5.197 + <title>A tour through history</title> 5.198 + 5.199 + <para id="x_1b">One of the first things we might want to do with a new, 5.200 + unfamiliar repository is understand its history. The <command 5.201 + role="hg-cmd">hg log</command> command gives us a view of 5.202 + the history of changes in the repository.</para> 5.203 + 5.204 + &interaction.tour.log; 5.205 + 5.206 + <para id="x_1c">By default, this command prints a brief paragraph of output 5.207 + for each change to the project that was recorded. In Mercurial 5.208 + terminology, we call each of these recorded events a 5.209 + <emphasis>changeset</emphasis>, because it can contain a record 5.210 + of changes to several files.</para> 5.211 + 5.212 + <para id="x_1d">The fields in a record of output from <command 5.213 + role="hg-cmd">hg log</command> are as follows.</para> 5.214 + 5.215 + <itemizedlist> 5.216 + <listitem><para id="x_1e"><literal>changeset</literal>: This 5.217 + field has the format of a number, followed by a colon, 5.218 + followed by a hexadecimal (or <emphasis>hex</emphasis>) 5.219 + string. These are <emphasis>identifiers</emphasis> for the 5.220 + changeset. The hex string is a unique identifier: the same 5.221 + hex string will always refer to the same changeset in every 5.222 + copy of this repository. The 5.223 + number is shorter and easier to type than the hex string, 5.224 + but it isn't unique: the same number in two different clones 5.225 + of a repository may identify different changesets.</para> 5.226 + </listitem> 5.227 + <listitem><para id="x_1f"><literal>user</literal>: The identity of the 5.228 + person who created the changeset. This is a free-form 5.229 + field, but it most often contains a person's name and email 5.230 + address.</para></listitem> 5.231 + <listitem><para id="x_20"><literal>date</literal>: The date and time on 5.232 + which the changeset was created, and the timezone in which 5.233 + it was created. (The date and time are local to that 5.234 + timezone; they display what time and date it was for the 5.235 + person who created the changeset.)</para></listitem> 5.236 + <listitem><para id="x_21"><literal>summary</literal>: The first line of 5.237 + the text message that the creator of the changeset entered 5.238 + to describe the changeset.</para></listitem> 5.239 + <listitem> 5.240 + <para id="x_67d">Some changesets, such as the first in the list above, 5.241 + have a <literal>tag</literal> field. A tag is another way 5.242 + to identify a changeset, by giving it an easy-to-remember 5.243 + name. (The tag named <literal>tip</literal> is special: it 5.244 + always refers to the newest change in a repository.)</para> 5.245 + </listitem> 5.246 + </itemizedlist> 5.247 + 5.248 + <para id="x_22">The default output printed by <command 5.249 + role="hg-cmd">hg log</command> is purely a summary; it is 5.250 + missing a lot of detail.</para> 5.251 + 5.252 + <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides 5.253 + a graphical representation of the history of the <filename 5.254 + class="directory">hello</filename> repository, to make it a 5.255 + little easier to see which direction history is 5.256 + <quote>flowing</quote> in. We'll be returning to this figure 5.257 + several times in this chapter and the chapter that 5.258 + follows.</para> 5.259 + 5.260 + <figure id="fig:tour-basic:history"> 5.261 + <title>Graphical history of the <filename 5.262 + class="directory">hello</filename> repository</title> 5.263 + <mediaobject> 5.264 + <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject> 5.265 + <textobject><phrase>XXX add text</phrase></textobject> 5.266 + </mediaobject> 5.267 + </figure> 5.268 + 5.269 + <sect2> 5.270 + <title>Changesets, revisions, and talking to other 5.271 + people</title> 5.272 + 5.273 + <para id="x_25">As English is a notoriously sloppy language, and computer 5.274 + science has a hallowed history of terminological confusion 5.275 + (why use one term when four will do?), revision control has a 5.276 + variety of words and phrases that mean the same thing. If you 5.277 + are talking about Mercurial history with other people, you 5.278 + will find that the word <quote>changeset</quote> is often 5.279 + compressed to <quote>change</quote> or (when written) 5.280 + <quote>cset</quote>, and sometimes a changeset is referred to 5.281 + as a <quote>revision</quote> or a <quote>rev</quote>.</para> 5.282 + 5.283 + <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you 5.284 + use to refer to the concept of <quote>a changeset</quote>, the 5.285 + <emphasis>identifier</emphasis> that you use to refer to 5.286 + <quote>a <emphasis>specific</emphasis> changeset</quote> is of 5.287 + great importance. Recall that the <literal>changeset</literal> 5.288 + field in the output from <command role="hg-cmd">hg 5.289 + log</command> identifies a changeset using both a number and 5.290 + a hexadecimal string.</para> 5.291 + <itemizedlist> 5.292 + <listitem><para id="x_27">The revision number is a handy 5.293 + notation that is <emphasis>only valid in that 5.294 + repository</emphasis>.</para></listitem> 5.295 + <listitem><para id="x_28">The hexadecimal string is the 5.296 + <emphasis>permanent, unchanging identifier</emphasis> that 5.297 + will always identify that exact changeset in 5.298 + <emphasis>every</emphasis> copy of the 5.299 + repository.</para></listitem></itemizedlist> 5.300 + 5.301 + <para id="x_29">This distinction is important. If you send 5.302 + someone an email talking about <quote>revision 33</quote>, 5.303 + there's a high likelihood that their revision 33 will 5.304 + <emphasis>not be the same</emphasis> as yours. The reason for 5.305 + this is that a revision number depends on the order in which 5.306 + changes arrived in a repository, and there is no guarantee 5.307 + that the same changes will happen in the same order in 5.308 + different repositories. Three changes <literal>a,b,c</literal> 5.309 + can easily appear in one repository as 5.310 + <literal>0,1,2</literal>, while in another as 5.311 + <literal>0,2,1</literal>.</para> 5.312 + 5.313 + <para id="x_2a">Mercurial uses revision numbers purely as a convenient 5.314 + shorthand. If you need to discuss a changeset with someone, 5.315 + or make a record of a changeset for some other reason (for 5.316 + example, in a bug report), use the hexadecimal 5.317 + identifier.</para> 5.318 + 5.319 + </sect2> 5.320 + <sect2> 5.321 + <title>Viewing specific revisions</title> 5.322 + 5.323 + <para id="x_2b">To narrow the output of <command role="hg-cmd">hg 5.324 + log</command> down to a single revision, use the <option 5.325 + role="hg-opt-log">-r</option> (or <option 5.326 + role="hg-opt-log">--rev</option>) option. You can use 5.327 + either a revision number or a hexadecimal identifier, 5.328 + and you can provide as many revisions as you want.</para> 5.329 + 5.330 + &interaction.tour.log-r; 5.331 + 5.332 + <para id="x_2c">If you want to see the history of several revisions 5.333 + without having to list each one, you can use <emphasis>range 5.334 + notation</emphasis>; this lets you express the idea <quote>I 5.335 + want all revisions between <literal>abc</literal> and 5.336 + <literal>def</literal>, inclusive</quote>.</para> 5.337 + 5.338 + &interaction.tour.log.range; 5.339 + 5.340 + <para id="x_2d">Mercurial also honours the order in which you specify 5.341 + revisions, so <command role="hg-cmd">hg log -r 2:4</command> 5.342 + prints 2, 3, and 4. while <command role="hg-cmd">hg log -r 5.343 + 4:2</command> prints 4, 3, and 2.</para> 5.344 + 5.345 + </sect2> 5.346 + <sect2> 5.347 + <title>More detailed information</title> 5.348 + 5.349 + <para id="x_2e">While the summary information printed by <command 5.350 + role="hg-cmd">hg log</command> is useful if you already know 5.351 + what you're looking for, you may need to see a complete 5.352 + description of the change, or a list of the files changed, if 5.353 + you're trying to decide whether a changeset is the one you're 5.354 + looking for. The <command role="hg-cmd">hg log</command> 5.355 + command's <option role="hg-opt-global">-v</option> (or <option 5.356 + role="hg-opt-global">--verbose</option>) option gives you 5.357 + this extra detail.</para> 5.358 + 5.359 + &interaction.tour.log-v; 5.360 + 5.361 + <para id="x_2f">If you want to see both the description and 5.362 + content of a change, add the <option 5.363 + role="hg-opt-log">-p</option> (or <option 5.364 + role="hg-opt-log">--patch</option>) option. This displays 5.365 + the content of a change as a <emphasis>unified diff</emphasis> 5.366 + (if you've never seen a unified diff before, see <xref 5.367 + linkend="sec:mq:patch"/> for an overview).</para> 5.368 + 5.369 + &interaction.tour.log-vp; 5.370 + 5.371 + <para id="x_67e">The <option role="hg-opt-log">-p</option> option is 5.372 + tremendously useful, so it's well worth remembering.</para> 5.373 + 5.374 + </sect2> 5.375 + </sect1> 5.376 + 5.377 + <sect1> 5.378 + <title>All about command options</title> 5.379 + 5.380 + <para id="x_30">Let's take a brief break from exploring Mercurial commands 5.381 + to discuss a pattern in the way that they work; you may find 5.382 + this useful to keep in mind as we continue our tour.</para> 5.383 + 5.384 + <para id="x_31">Mercurial has a consistent and straightforward approach to 5.385 + dealing with the options that you can pass to commands. It 5.386 + follows the conventions for options that are common to modern 5.387 + Linux and Unix systems.</para> 5.388 + 5.389 + <itemizedlist> 5.390 + <listitem> 5.391 + <para id="x_32">Every option has a long name. For example, as 5.392 + we've already seen, the <command role="hg-cmd">hg 5.393 + log</command> command accepts a <option 5.394 + role="hg-opt-log">--rev</option> option.</para> 5.395 + </listitem> 5.396 + <listitem> 5.397 + <para id="x_33">Most options have short names, too. Instead 5.398 + of <option role="hg-opt-log">--rev</option>, we can use 5.399 + <option role="hg-opt-log">-r</option>. (The reason that 5.400 + some options don't have short names is that the options in 5.401 + question are rarely used.)</para> 5.402 + </listitem> 5.403 + <listitem> 5.404 + <para id="x_34">Long options start with two dashes (e.g. 5.405 + <option role="hg-opt-log">--rev</option>), while short 5.406 + options start with one (e.g. <option 5.407 + role="hg-opt-log">-r</option>).</para> 5.408 + </listitem> 5.409 + <listitem> 5.410 + <para id="x_35">Option naming and usage is consistent across 5.411 + commands. For example, every command that lets you specify 5.412 + a changeset ID or revision number accepts both <option 5.413 + role="hg-opt-log">-r</option> and <option 5.414 + role="hg-opt-log">--rev</option> arguments.</para> 5.415 + </listitem> 5.416 + <listitem> 5.417 + <para id="x_67f">If you are using short options, you can save typing by 5.418 + running them together. For example, the command <command 5.419 + role="hg-cmd">hg log -v -p -r 2</command> can be written 5.420 + as <command role="hg-cmd">hg log -vpr2</command>.</para> 5.421 + </listitem> 5.422 + </itemizedlist> 5.423 + 5.424 + <para id="x_36">In the examples throughout this book, I usually 5.425 + use short options instead of long. This simply reflects my own 5.426 + preference, so don't read anything significant into it.</para> 5.427 + 5.428 + <para id="x_37">Most commands that print output of some kind will print more 5.429 + output when passed a <option role="hg-opt-global">-v</option> 5.430 + (or <option role="hg-opt-global">--verbose</option>) option, and 5.431 + less when passed <option role="hg-opt-global">-q</option> (or 5.432 + <option role="hg-opt-global">--quiet</option>).</para> 5.433 + 5.434 + <note> 5.435 + <title>Option naming consistency</title> 5.436 + 5.437 + <para id="x_680">Almost always, Mercurial commands use consistent option 5.438 + names to refer to the same concepts. For instance, if a 5.439 + command deals with changesets, you'll always identify them 5.440 + with <option role="hg-opt-log">--rev</option> or <option 5.441 + role="hg-opt-log">-r</option>. This consistent use of 5.442 + option names makes it easier to remember what options a 5.443 + particular command takes.</para> 5.444 + </note> 5.445 + 5.446 + </sect1> 5.447 + <sect1> 5.448 + <title>Making and reviewing changes</title> 5.449 + 5.450 + <para id="x_38">Now that we have a grasp of viewing history in Mercurial, 5.451 + let's take a look at making some changes and examining 5.452 + them.</para> 5.453 + 5.454 + <para id="x_39">The first thing we'll do is isolate our experiment in a 5.455 + repository of its own. We use the <command role="hg-cmd">hg 5.456 + clone</command> command, but we don't need to clone a copy of 5.457 + the remote repository. Since we already have a copy of it 5.458 + locally, we can just clone that instead. This is much faster 5.459 + than cloning over the network, and cloning a local repository 5.460 + uses less disk space in most cases, too<footnote> 5.461 + <para id="x_681">The saving of space arises when source and destination 5.462 + repositories are on the same filesystem, in which case 5.463 + Mercurial will use hardlinks to do copy-on-write sharing of 5.464 + its internal metadata. If that explanation meant nothing to 5.465 + you, don't worry: everything happens transparently and 5.466 + automatically, and you don't need to understand it.</para> 5.467 + </footnote>.</para> 5.468 + 5.469 + &interaction.tour.reclone; 5.470 + 5.471 + <para id="x_3a">As an aside, it's often good practice to keep a 5.472 + <quote>pristine</quote> copy of a remote repository around, 5.473 + which you can then make temporary clones of to create sandboxes 5.474 + for each task you want to work on. This lets you work on 5.475 + multiple tasks in parallel, each isolated from the others until 5.476 + it's complete and you're ready to integrate it back. Because 5.477 + local clones are so cheap, there's almost no overhead to cloning 5.478 + and destroying repositories whenever you want.</para> 5.479 + 5.480 + <para id="x_3b">In our <filename class="directory">my-hello</filename> 5.481 + repository, we have a file <filename>hello.c</filename> that 5.482 + contains the classic <quote>hello, world</quote> program.</para> 5.483 + 5.484 + &interaction.tour.cat1; 5.485 + 5.486 + <para id="x_682">Let's edit this file so that it prints a second line of 5.487 + output.</para> 5.488 + 5.489 + &interaction.tour.cat2; 5.490 + 5.491 + <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> 5.492 + command will tell us what Mercurial knows about the files in the 5.493 + repository.</para> 5.494 + 5.495 + &interaction.tour.status; 5.496 + 5.497 + <para id="x_3d">The <command role="hg-cmd">hg status</command> command 5.498 + prints no output for some files, but a line starting with 5.499 + <quote><literal>M</literal></quote> for 5.500 + <filename>hello.c</filename>. Unless you tell it to, <command 5.501 + role="hg-cmd">hg status</command> will not print any output 5.502 + for files that have not been modified.</para> 5.503 + 5.504 + <para id="x_3e">The <quote><literal>M</literal></quote> indicates that 5.505 + Mercurial has noticed that we modified 5.506 + <filename>hello.c</filename>. We didn't need to 5.507 + <emphasis>inform</emphasis> Mercurial that we were going to 5.508 + modify the file before we started, or that we had modified the 5.509 + file after we were done; it was able to figure this out 5.510 + itself.</para> 5.511 + 5.512 + <para id="x_3f">It's somewhat helpful to know that we've modified 5.513 + <filename>hello.c</filename>, but we might prefer to know 5.514 + exactly <emphasis>what</emphasis> changes we've made to it. To 5.515 + do this, we use the <command role="hg-cmd">hg diff</command> 5.516 + command.</para> 5.517 + 5.518 + &interaction.tour.diff; 5.519 + 5.520 + <tip> 5.521 + <title>Understanding patches</title> 5.522 + 5.523 + <para id="x_683">Remember to take a look at <xref 5.524 + linkend="sec:mq:patch"/> if you don't know how to read 5.525 + output above.</para> 5.526 + </tip> 5.527 + </sect1> 5.528 + <sect1> 5.529 + <title>Recording changes in a new changeset</title> 5.530 + 5.531 + <para id="x_40">We can modify files, build and test our changes, and use 5.532 + <command role="hg-cmd">hg status</command> and <command 5.533 + role="hg-cmd">hg diff</command> to review our changes, until 5.534 + we're satisfied with what we've done and arrive at a natural 5.535 + stopping point where we want to record our work in a new 5.536 + changeset.</para> 5.537 + 5.538 + <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets 5.539 + us create a new changeset; we'll usually refer to this as 5.540 + <quote>making a commit</quote> or 5.541 + <quote>committing</quote>.</para> 5.542 + 5.543 + <sect2> 5.544 + <title>Setting up a username</title> 5.545 + 5.546 + <para id="x_42">When you try to run <command role="hg-cmd">hg 5.547 + commit</command> for the first time, it is not guaranteed to 5.548 + succeed. Mercurial records your name and address with each 5.549 + change that you commit, so that you and others will later be 5.550 + able to tell who made each change. Mercurial tries to 5.551 + automatically figure out a sensible username to commit the 5.552 + change with. It will attempt each of the following methods, 5.553 + in order:</para> 5.554 + <orderedlist> 5.555 + <listitem><para id="x_43">If you specify a <option 5.556 + role="hg-opt-commit">-u</option> option to the <command 5.557 + role="hg-cmd">hg commit</command> command on the command 5.558 + line, followed by a username, this is always given the 5.559 + highest precedence.</para></listitem> 5.560 + <listitem><para id="x_44">If you have set the <envar>HGUSER</envar> 5.561 + environment variable, this is checked 5.562 + next.</para></listitem> 5.563 + <listitem><para id="x_45">If you create a file in your home 5.564 + directory called <filename 5.565 + role="special">.hgrc</filename>, with a <envar 5.566 + role="rc-item-ui">username</envar> entry, that will be 5.567 + used next. To see what the contents of this file should 5.568 + look like, refer to <xref 5.569 + linkend="sec:tour-basic:username"/> 5.570 + below.</para></listitem> 5.571 + <listitem><para id="x_46">If you have set the <envar>EMAIL</envar> 5.572 + environment variable, this will be used 5.573 + next.</para></listitem> 5.574 + <listitem><para id="x_47">Mercurial will query your system to find out 5.575 + your local user name and host name, and construct a 5.576 + username from these components. Since this often results 5.577 + in a username that is not very useful, it will print a 5.578 + warning if it has to do 5.579 + this.</para></listitem> 5.580 + </orderedlist> 5.581 + <para id="x_48">If all of these mechanisms fail, Mercurial will 5.582 + fail, printing an error message. In this case, it will not 5.583 + let you commit until you set up a 5.584 + username.</para> 5.585 + <para id="x_49">You should think of the <envar>HGUSER</envar> environment 5.586 + variable and the <option role="hg-opt-commit">-u</option> 5.587 + option to the <command role="hg-cmd">hg commit</command> 5.588 + command as ways to <emphasis>override</emphasis> Mercurial's 5.589 + default selection of username. For normal use, the simplest 5.590 + and most robust way to set a username for yourself is by 5.591 + creating a <filename role="special">.hgrc</filename> file; see 5.592 + below for details.</para> 5.593 + <sect3 id="sec:tour-basic:username"> 5.594 + <title>Creating a Mercurial configuration file</title> 5.595 + 5.596 + <para id="x_4a">To set a user name, use your favorite editor 5.597 + to create a file called <filename 5.598 + role="special">.hgrc</filename> in your home directory. 5.599 + Mercurial will use this file to look up your personalised 5.600 + configuration settings. The initial contents of your 5.601 + <filename role="special">.hgrc</filename> should look like 5.602 + this.</para> 5.603 + 5.604 + <tip> 5.605 + <title><quote>Home directory</quote> on Windows</title> 5.606 + 5.607 + <para id="x_716">When we refer to your home directory, on an English 5.608 + language installation of Windows this will usually be a 5.609 + folder named after your user name in 5.610 + <filename>C:\Documents and Settings</filename>. You can 5.611 + find out the exact name of your home directory by opening 5.612 + a command prompt window and running the following 5.613 + command.</para> 5.614 + 5.615 + <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen> 5.616 + </tip> 5.617 + 5.618 + <programlisting># This is a Mercurial configuration file. 5.619 +[ui] 5.620 +username = Firstname Lastname <email.address@example.net></programlisting> 5.621 + 5.622 + <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a 5.623 + <emphasis>section</emphasis> of the config file, so you can 5.624 + read the <quote><literal>username = ...</literal></quote> 5.625 + line as meaning <quote>set the value of the 5.626 + <literal>username</literal> item in the 5.627 + <literal>ui</literal> section</quote>. A section continues 5.628 + until a new section begins, or the end of the file. 5.629 + Mercurial ignores empty lines and treats any text from 5.630 + <quote><literal>#</literal></quote> to the end of a line as 5.631 + a comment.</para> 5.632 + </sect3> 5.633 + 5.634 + <sect3> 5.635 + <title>Choosing a user name</title> 5.636 + 5.637 + <para id="x_4c">You can use any text you like as the value of 5.638 + the <literal>username</literal> config item, since this 5.639 + information is for reading by other people, but will not be 5.640 + interpreted by Mercurial. The convention that most people 5.641 + follow is to use their name and email address, as in the 5.642 + example above.</para> 5.643 + <note> 5.644 + <para id="x_4d">Mercurial's built-in web server obfuscates 5.645 + email addresses, to make it more difficult for the email 5.646 + harvesting tools that spammers use. This reduces the 5.647 + likelihood that you'll start receiving more junk email if 5.648 + you publish a Mercurial repository on the 5.649 + web.</para></note> 5.650 + </sect3> 5.651 + </sect2> 5.652 + <sect2> 5.653 + <title>Writing a commit message</title> 5.654 + 5.655 + <para id="x_4e">When we commit a change, Mercurial drops us into 5.656 + a text editor, to enter a message that will describe the 5.657 + modifications we've made in this changeset. This is called 5.658 + the <emphasis>commit message</emphasis>. It will be a record 5.659 + for readers of what we did and why, and it will be printed by 5.660 + <command role="hg-cmd">hg log</command> after we've finished 5.661 + committing.</para> 5.662 + 5.663 + &interaction.tour.commit; 5.664 + 5.665 + <para id="x_4f">The editor that the <command role="hg-cmd">hg 5.666 + commit</command> command drops us into will contain an empty 5.667 + line or two, followed by a number of lines starting with 5.668 + <quote><literal>HG:</literal></quote>.</para> 5.669 + 5.670 + <programlisting> 5.671 +This is where I type my commit comment. 5.672 + 5.673 +HG: Enter commit message. Lines beginning with 'HG:' are removed. 5.674 +HG: -- 5.675 +HG: user: Bryan O'Sullivan <bos@serpentine.com> 5.676 +HG: branch 'default' 5.677 +HG: changed hello.c</programlisting> 5.678 + 5.679 + <para id="x_50">Mercurial ignores the lines that start with 5.680 + <quote><literal>HG:</literal></quote>; it uses them only to 5.681 + tell us which files it's recording changes to. Modifying or 5.682 + deleting these lines has no effect.</para> 5.683 + </sect2> 5.684 + <sect2> 5.685 + <title>Writing a good commit message</title> 5.686 + 5.687 + <para id="x_51">Since <command role="hg-cmd">hg log</command> 5.688 + only prints the first line of a commit message by default, 5.689 + it's best to write a commit message whose first line stands 5.690 + alone. Here's a real example of a commit message that 5.691 + <emphasis>doesn't</emphasis> follow this guideline, and hence 5.692 + has a summary that is not readable.</para> 5.693 + 5.694 + <programlisting> 5.695 +changeset: 73:584af0e231be 5.696 +user: Censored Person <censored.person@example.org> 5.697 +date: Tue Sep 26 21:37:07 2006 -0700 5.698 +summary: include buildmeister/commondefs. Add exports.</programlisting> 5.699 + 5.700 + <para id="x_52">As far as the remainder of the contents of the 5.701 + commit message are concerned, there are no hard-and-fast 5.702 + rules. Mercurial itself doesn't interpret or care about the 5.703 + contents of the commit message, though your project may have 5.704 + policies that dictate a certain kind of formatting.</para> 5.705 + <para id="x_53">My personal preference is for short, but 5.706 + informative, commit messages that tell me something that I 5.707 + can't figure out with a quick glance at the output of <command 5.708 + role="hg-cmd">hg log --patch</command>.</para> 5.709 + <para id="x_55">If we run the <command role="hg-cmd">hg 5.710 + commit</command> command without any arguments, it records 5.711 + all of the changes we've made, as reported by <command 5.712 + role="hg-cmd">hg status</command> and <command 5.713 + role="hg-cmd">hg diff</command>.</para> 5.714 + 5.715 + <note> 5.716 + <title>A surprise for Subversion users</title> 5.717 + 5.718 + <para id="x_717">Like other Mercurial commands, if we don't supply 5.719 + explicit names to commit to the <command role="hg-cmd">hg 5.720 + commit</command>, it will operate across a repository's 5.721 + entire working directory. Be wary of this if you're coming 5.722 + from the Subversion or CVS world, since you might expect it 5.723 + to operate only on the current directory that you happen to 5.724 + be visiting and its subdirectories.</para> 5.725 + </note> 5.726 + </sect2> 5.727 + 5.728 + <sect2> 5.729 + <title>Aborting a commit</title> 5.730 + 5.731 + <para id="x_54">If you decide that you don't want to commit 5.732 + while in the middle of editing a commit message, simply exit 5.733 + from your editor without saving the file that it's editing. 5.734 + This will cause nothing to happen to either the repository or 5.735 + the working directory.</para> 5.736 + </sect2> 5.737 + 5.738 + <sect2> 5.739 + <title>Admiring our new handiwork</title> 5.740 + 5.741 + <para id="x_56">Once we've finished the commit, we can use the 5.742 + <command role="hg-cmd">hg tip</command> command to display the 5.743 + changeset we just created. This command produces output that 5.744 + is identical to <command role="hg-cmd">hg log</command>, but 5.745 + it only displays the newest revision in the repository.</para> 5.746 + 5.747 + &interaction.tour.tip; 5.748 + 5.749 + <para id="x_57">We refer to the newest revision in the 5.750 + repository as the <emphasis>tip revision</emphasis>, or simply 5.751 + the <emphasis>tip</emphasis>.</para> 5.752 + 5.753 + <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command> 5.754 + command accepts many of the same options as <command 5.755 + role="hg-cmd">hg log</command>, so <option 5.756 + role="hg-opt-global">-v</option> above indicates <quote>be 5.757 + verbose</quote>, <option role="hg-opt-tip">-p</option> 5.758 + specifies <quote>print a patch</quote>. The use of <option 5.759 + role="hg-opt-tip">-p</option> to print patches is another 5.760 + example of the consistent naming we mentioned earlier.</para> 5.761 + </sect2> 5.762 + </sect1> 5.763 + 5.764 + <sect1> 5.765 + <title>Sharing changes</title> 5.766 + 5.767 + <para id="x_58">We mentioned earlier that repositories in 5.768 + Mercurial are self-contained. This means that the changeset we 5.769 + just created exists only in our <filename 5.770 + class="directory">my-hello</filename> repository. Let's look 5.771 + at a few ways that we can propagate this change into other 5.772 + repositories.</para> 5.773 + 5.774 + <sect2 id="sec:tour:pull"> 5.775 + <title>Pulling changes from another repository</title> 5.776 + 5.777 + <para id="x_59">To get started, let's clone our original 5.778 + <filename class="directory">hello</filename> repository, which 5.779 + does not contain the change we just committed. We'll call our 5.780 + temporary repository <filename 5.781 + class="directory">hello-pull</filename>.</para> 5.782 + 5.783 + &interaction.tour.clone-pull; 5.784 + 5.785 + <para id="x_5a">We'll use the <command role="hg-cmd">hg 5.786 + pull</command> command to bring changes from <filename 5.787 + class="directory">my-hello</filename> into <filename 5.788 + class="directory">hello-pull</filename>. However, blindly 5.789 + pulling unknown changes into a repository is a somewhat scary 5.790 + prospect. Mercurial provides the <command role="hg-cmd">hg 5.791 + incoming</command> command to tell us what changes the 5.792 + <command role="hg-cmd">hg pull</command> command 5.793 + <emphasis>would</emphasis> pull into the repository, without 5.794 + actually pulling the changes in.</para> 5.795 + 5.796 + &interaction.tour.incoming; 5.797 + 5.798 + <para id="x_5c">Bringing changes into a repository is a simple 5.799 + matter of running the <command role="hg-cmd">hg pull</command> 5.800 + command, and optionally telling it which repository to pull from.</para> 5.801 + 5.802 + &interaction.tour.pull; 5.803 + 5.804 + <para id="x_5d">As you can see from the before-and-after output 5.805 + of <command role="hg-cmd">hg tip</command>, we have 5.806 + successfully pulled changes into our repository. However, 5.807 + Mercurial separates pulling changes in from updating the 5.808 + working directory. There remains one step before we will see 5.809 + the changes that we just pulled appear in the working 5.810 + directory.</para> 5.811 + 5.812 + <tip> 5.813 + <title>Pulling specific changes</title> 5.814 + 5.815 + <para id="x_5b">It is possible that due to the delay between 5.816 + running <command role="hg-cmd">hg incoming</command> and 5.817 + <command role="hg-cmd">hg pull</command>, you may not see 5.818 + all changesets that will be brought from the other 5.819 + repository. Suppose you're pulling changes from a repository 5.820 + on the network somewhere. While you are looking at the 5.821 + <command role="hg-cmd">hg incoming</command> output, and 5.822 + before you pull those changes, someone might have committed 5.823 + something in the remote repository. This means that it's 5.824 + possible to pull more changes than you saw when using 5.825 + <command role="hg-cmd">hg incoming</command>.</para> 5.826 + 5.827 + <para id="x_718">If you only want to pull precisely the changes that were 5.828 + listed by <command role="hg-cmd">hg incoming</command>, or 5.829 + you have some other reason to pull a subset of changes, 5.830 + simply identify the change that you want to pull by its 5.831 + changeset ID, e.g. <command>hg pull 5.832 + -r7e95bb</command>.</para> 5.833 + </tip> 5.834 + </sect2> 5.835 + 5.836 + <sect2> 5.837 + <title>Updating the working directory</title> 5.838 + 5.839 + <para id="x_5e">We have so far glossed over the relationship 5.840 + between a repository and its working directory. The <command 5.841 + role="hg-cmd">hg pull</command> command that we ran in 5.842 + <xref linkend="sec:tour:pull"/> brought changes into the 5.843 + repository, but if we check, there's no sign of those changes 5.844 + in the working directory. This is because <command 5.845 + role="hg-cmd">hg pull</command> does not (by default) touch 5.846 + the working directory. Instead, we use the <command 5.847 + role="hg-cmd">hg update</command> command to do this.</para> 5.848 + 5.849 + &interaction.tour.update; 5.850 + 5.851 + <para id="x_5f">It might seem a bit strange that <command 5.852 + role="hg-cmd">hg pull</command> doesn't update the working 5.853 + directory automatically. There's actually a good reason for 5.854 + this: you can use <command role="hg-cmd">hg update</command> 5.855 + to update the working directory to the state it was in at 5.856 + <emphasis>any revision</emphasis> in the history of the 5.857 + repository. If you had the working directory updated to an 5.858 + old revision&emdash;to hunt down the origin of a bug, 5.859 + say&emdash;and ran a <command role="hg-cmd">hg pull</command> 5.860 + which automatically updated the working directory to a new 5.861 + revision, you might not be terribly happy.</para> 5.862 + 5.863 + <para id="x_60">Since pull-then-update is such a common sequence 5.864 + of operations, Mercurial lets you combine the two by passing 5.865 + the <option role="hg-opt-pull">-u</option> option to <command 5.866 + role="hg-cmd">hg pull</command>.</para> 5.867 + 5.868 + <para id="x_61">If you look back at the output of <command 5.869 + role="hg-cmd">hg pull</command> in <xref 5.870 + linkend="sec:tour:pull"/> when we ran it without <option 5.871 + role="hg-opt-pull">-u</option>, you can see that it printed 5.872 + a helpful reminder that we'd have to take an explicit step to 5.873 + update the working directory.</para> 5.874 + 5.875 + <para id="x_62">To find out what revision the working directory 5.876 + is at, use the <command role="hg-cmd">hg parents</command> 5.877 + command.</para> 5.878 + 5.879 + &interaction.tour.parents; 5.880 + 5.881 + <para id="x_63">If you look back at <xref 5.882 + linkend="fig:tour-basic:history"/>, you'll see arrows 5.883 + connecting each changeset. The node that the arrow leads 5.884 + <emphasis>from</emphasis> in each case is a parent, and the 5.885 + node that the arrow leads <emphasis>to</emphasis> is its 5.886 + child. The working directory has a parent in just the same 5.887 + way; this is the changeset that the working directory 5.888 + currently contains.</para> 5.889 + 5.890 + <para id="x_64">To update the working directory to a particular 5.891 + revision, give a revision number or changeset ID to the 5.892 + <command role="hg-cmd">hg update</command> command.</para> 5.893 + 5.894 + &interaction.tour.older; 5.895 + 5.896 + <para id="x_65">If you omit an explicit revision, <command 5.897 + role="hg-cmd">hg update</command> will update to the tip 5.898 + revision, as shown by the second call to <command 5.899 + role="hg-cmd">hg update</command> in the example 5.900 + above.</para> 5.901 + </sect2> 5.902 + 5.903 + <sect2> 5.904 + <title>Pushing changes to another repository</title> 5.905 + 5.906 + <para id="x_66">Mercurial lets us push changes to another 5.907 + repository, from the repository we're currently visiting. As 5.908 + with the example of <command role="hg-cmd">hg pull</command> 5.909 + above, we'll create a temporary repository to push our changes 5.910 + into.</para> 5.911 + 5.912 + &interaction.tour.clone-push; 5.913 + 5.914 + <para id="x_67">The <command role="hg-cmd">hg outgoing</command> 5.915 + command tells us what changes would be pushed into another 5.916 + repository.</para> 5.917 + 5.918 + &interaction.tour.outgoing; 5.919 + 5.920 + <para id="x_68">And the <command role="hg-cmd">hg push</command> 5.921 + command does the actual push.</para> 5.922 + 5.923 + &interaction.tour.push; 5.924 + 5.925 + <para id="x_69">As with <command role="hg-cmd">hg 5.926 + pull</command>, the <command role="hg-cmd">hg push</command> 5.927 + command does not update the working directory in the 5.928 + repository that it's pushing changes into. Unlike <command 5.929 + role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg 5.930 + push</command> does not provide a <literal>-u</literal> 5.931 + option that updates the other repository's working directory. 5.932 + This asymmetry is deliberate: the repository we're pushing to 5.933 + might be on a remote server and shared between several people. 5.934 + If we were to update its working directory while someone was 5.935 + working in it, their work would be disrupted.</para> 5.936 + 5.937 + <para id="x_6a">What happens if we try to pull or push changes 5.938 + and the receiving repository already has those changes? 5.939 + Nothing too exciting.</para> 5.940 + 5.941 + &interaction.tour.push.nothing; 5.942 + </sect2> 5.943 + 5.944 + <sect2> 5.945 + <title>Default locations</title> 5.946 + 5.947 + <para id="x_719">When we clone a repository, Mercurial records the location 5.948 + of the repository we cloned in the 5.949 + <filename>.hg/hgrc</filename> file of the new repository. If 5.950 + we don't supply a location to <command>hg pull</command> from 5.951 + or <command>hg push</command> to, those commands will use this 5.952 + location as a default. The <command>hg incoming</command> 5.953 + and <command>hg outgoing</command> commands do so too.</para> 5.954 + 5.955 + <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename> 5.956 + file in a text editor, you will see contents like the 5.957 + following.</para> 5.958 + 5.959 + <programlisting>[paths] 5.960 +default = http://www.selenic.com/repo/hg</programlisting> 5.961 + 5.962 + <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the 5.963 + default location for <command>hg push</command> and 5.964 + <command>hg outgoing</command> be different from those for 5.965 + <command>hg pull</command> and <command>hg incoming</command>. 5.966 + We can do this by adding a <literal>default-push</literal> 5.967 + entry to the <literal>[paths]</literal> section of the 5.968 + <filename>.hg/hgrc</filename> file, as follows.</para> 5.969 + 5.970 + <programlisting>[paths] 5.971 +default = http://www.selenic.com/repo/hg 5.972 +default-push = http://hg.example.com/hg</programlisting> 5.973 + </sect2> 5.974 + 5.975 + <sect2> 5.976 + <title>Sharing changes over a network</title> 5.977 + 5.978 + <para id="x_6b">The commands we have covered in the previous few 5.979 + sections are not limited to working with local repositories. 5.980 + Each works in exactly the same fashion over a network 5.981 + connection; simply pass in a URL instead of a local 5.982 + path.</para> 5.983 + 5.984 + &interaction.tour.outgoing.net; 5.985 + 5.986 + <para id="x_6c">In this example, we can see what changes we 5.987 + could push to the remote repository, but the repository is 5.988 + understandably not set up to let anonymous users push to 5.989 + it.</para> 5.990 + 5.991 + &interaction.tour.push.net; 5.992 + </sect2> 5.993 + </sect1> 5.994 + 5.995 + <sect1> 5.996 + <title>Starting a new project</title> 5.997 + 5.998 + <para id="x_71c">It is just as easy to begin a new project as to work on one 5.999 + that already exists. The <command>hg init</command> command 5.1000 + creates a new, empty Mercurial repository.</para> 5.1001 + 5.1002 + &interaction.ch01-new.init; 5.1003 + 5.1004 + <para id="x_71d">This simply creates a repository named 5.1005 + <filename>myproject</filename> in the current directory.</para> 5.1006 + 5.1007 + &interaction.ch01-new.ls; 5.1008 + 5.1009 + <para id="x_71e">We can tell that <filename>myproject</filename> is a 5.1010 + Mercurial repository, because it contains a 5.1011 + <filename>.hg</filename> directory.</para> 5.1012 + 5.1013 + &interaction.ch01-new.ls2; 5.1014 + 5.1015 + <para id="x_71f">If we want to add some pre-existing files to the repository, 5.1016 + we copy them into place, and tell Mercurial to start tracking 5.1017 + them using the <command>hg add</command> command.</para> 5.1018 + 5.1019 + &interaction.ch01-new.add; 5.1020 + 5.1021 + <para id="x_720">Once we are satisfied that our project looks right, we 5.1022 + commit our changes.</para> 5.1023 + 5.1024 + &interaction.ch01-new.commit; 5.1025 + 5.1026 + <para id="x_721">It takes just a few moments to start using Mercurial on a 5.1027 + new project, which is part of its appeal. Revision control is 5.1028 + now so easy to work with, we can use it on the smallest of 5.1029 + projects that we might not have considered with a more 5.1030 + complicated tool.</para> 5.1031 + </sect1> 5.1032 +</chapter> 5.1033 + 5.1034 +<!-- 5.1035 +local variables: 5.1036 +sgml-parent-document: ("00book.xml" "book" "chapter") 5.1037 +end: 5.1038 +-->
6.1 --- a/en/ch02-tour-merge.xml Thu May 07 21:06:49 2009 -0700 6.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 6.3 @@ -1,454 +0,0 @@ 6.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 6.5 - 6.6 -<chapter id="chap:tour-merge"> 6.7 - <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?> 6.8 - <title>A tour of Mercurial: merging work</title> 6.9 - 6.10 - <para id="x_338">We've now covered cloning a repository, making changes in a 6.11 - repository, and pulling or pushing changes from one repository 6.12 - into another. Our next step is <emphasis>merging</emphasis> 6.13 - changes from separate repositories.</para> 6.14 - 6.15 - <sect1> 6.16 - <title>Merging streams of work</title> 6.17 - 6.18 - <para id="x_339">Merging is a fundamental part of working with a distributed 6.19 - revision control tool. Here are a few cases in which the need 6.20 - to merge work arises.</para> 6.21 - <itemizedlist> 6.22 - <listitem> 6.23 - <para id="x_33a">Alice and Bob each have a personal copy of a 6.24 - repository for a project they're collaborating on. Alice 6.25 - fixes a bug in her repository; Bob adds a new feature in 6.26 - his. They want the shared repository to contain both the 6.27 - bug fix and the new feature.</para> 6.28 - </listitem> 6.29 - <listitem> 6.30 - <para id="x_33b">Cynthia frequently works on several different 6.31 - tasks for a single project at once, each safely isolated in 6.32 - its own repository. Working this way means that she often 6.33 - needs to merge one piece of her own work with 6.34 - another.</para> 6.35 - </listitem> 6.36 - </itemizedlist> 6.37 - 6.38 - <para id="x_33c">Because we need to merge often, Mercurial makes 6.39 - the process easy. Let's walk through a merge. We'll begin by 6.40 - cloning yet another repository (see how often they spring up?) 6.41 - and making a change in it.</para> 6.42 - 6.43 - &interaction.tour.merge.clone; 6.44 - 6.45 - <para id="x_33d">We should now have two copies of 6.46 - <filename>hello.c</filename> with different contents. The 6.47 - histories of the two repositories have also diverged, as 6.48 - illustrated in <xref 6.49 - linkend="fig:tour-merge:sep-repos"/>. Here is a copy of our 6.50 - file from one repository.</para> 6.51 - 6.52 - &interaction.tour.merge.cat1; 6.53 - 6.54 - <para id="x_722">And here is our slightly different version from the other 6.55 - repository.</para> 6.56 - 6.57 - &interaction.tour.merge.cat2; 6.58 - 6.59 - <figure id="fig:tour-merge:sep-repos"> 6.60 - <title>Divergent recent histories of the <filename 6.61 - class="directory">my-hello</filename> and <filename 6.62 - class="directory">my-new-hello</filename> 6.63 - repositories</title> 6.64 - <mediaobject> 6.65 - <imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject> 6.66 - <textobject><phrase>XXX add text</phrase></textobject> 6.67 - </mediaobject> 6.68 - </figure> 6.69 - 6.70 - <para id="x_33f">We already know that pulling changes from our <filename 6.71 - class="directory">my-hello</filename> repository will have no 6.72 - effect on the working directory.</para> 6.73 - 6.74 - &interaction.tour.merge.pull; 6.75 - 6.76 - <para id="x_340">However, the <command role="hg-cmd">hg pull</command> 6.77 - command says something about <quote>heads</quote>.</para> 6.78 - 6.79 - <sect2> 6.80 - <title>Head changesets</title> 6.81 - 6.82 - <para id="x_341">Remember that Mercurial records what the parent 6.83 - of each change is. If a change has a parent, we call it a 6.84 - child or descendant of the parent. A head is a change that 6.85 - has no children. The tip revision is thus a head, because the 6.86 - newest revision in a repository doesn't have any children. 6.87 - There are times when a repository can contain more than one 6.88 - head.</para> 6.89 - 6.90 - <figure id="fig:tour-merge:pull"> 6.91 - <title>Repository contents after pulling from <filename 6.92 - class="directory">my-hello</filename> into <filename 6.93 - class="directory">my-new-hello</filename></title> 6.94 - <mediaobject> 6.95 - <imageobject> 6.96 - <imagedata fileref="figs/tour-merge-pull.png"/> 6.97 - </imageobject> 6.98 - <textobject><phrase>XXX add text</phrase></textobject> 6.99 - </mediaobject> 6.100 - </figure> 6.101 - 6.102 - <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can 6.103 - see the effect of the pull from <filename 6.104 - class="directory">my-hello</filename> into <filename 6.105 - class="directory">my-new-hello</filename>. The history that 6.106 - was already present in <filename 6.107 - class="directory">my-new-hello</filename> is untouched, but 6.108 - a new revision has been added. By referring to <xref 6.109 - linkend="fig:tour-merge:sep-repos"/>, we can see that the 6.110 - <emphasis>changeset ID</emphasis> remains the same in the new 6.111 - repository, but the <emphasis>revision number</emphasis> has 6.112 - changed. (This, incidentally, is a fine example of why it's 6.113 - not safe to use revision numbers when discussing changesets.) 6.114 - We can view the heads in a repository using the <command 6.115 - role="hg-cmd">hg heads</command> command.</para> 6.116 - 6.117 - &interaction.tour.merge.heads; 6.118 - </sect2> 6.119 - 6.120 - <sect2> 6.121 - <title>Performing the merge</title> 6.122 - 6.123 - <para id="x_344">What happens if we try to use the normal <command 6.124 - role="hg-cmd">hg update</command> command to update to the 6.125 - new tip?</para> 6.126 - 6.127 - &interaction.tour.merge.update; 6.128 - 6.129 - <para id="x_345">Mercurial is telling us that the <command 6.130 - role="hg-cmd">hg update</command> command won't do a merge; 6.131 - it won't update the working directory when it thinks we might 6.132 - want to do a merge, unless we force it to do so. 6.133 - (Incidentally, forcing the update with <command>hg update 6.134 - -C</command> would revert any uncommitted changes in the 6.135 - working directory.)</para> 6.136 - 6.137 - <para id="x_723">To start a merge between the two heads, we use the 6.138 - <command role="hg-cmd">hg merge</command> command.</para> 6.139 - 6.140 - &interaction.tour.merge.merge; 6.141 - 6.142 - <para id="x_347">We resolve the contents of <filename>hello.c</filename> 6.143 - 6.144 -This updates the working directory so that it 6.145 - contains changes from <emphasis>both</emphasis> heads, which 6.146 - is reflected in both the output of <command role="hg-cmd">hg 6.147 - parents</command> and the contents of 6.148 - <filename>hello.c</filename>.</para> 6.149 - 6.150 - &interaction.tour.merge.parents; 6.151 - </sect2> 6.152 - 6.153 - <sect2> 6.154 - <title>Committing the results of the merge</title> 6.155 - 6.156 - <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg 6.157 - parents</command> will display two parents until we <command 6.158 - role="hg-cmd">hg commit</command> the results of the 6.159 - merge.</para> 6.160 - 6.161 - &interaction.tour.merge.commit; 6.162 - 6.163 - <para id="x_349">We now have a new tip revision; notice that it has 6.164 - <emphasis>both</emphasis> of our former heads as its parents. 6.165 - These are the same revisions that were previously displayed by 6.166 - <command role="hg-cmd">hg parents</command>.</para> 6.167 - 6.168 - &interaction.tour.merge.tip; 6.169 - 6.170 - <para id="x_34a">In <xref 6.171 - linkend="fig:tour-merge:merge"/>, you can see a 6.172 - representation of what happens to the working directory during 6.173 - the merge, and how this affects the repository when the commit 6.174 - happens. During the merge, the working directory has two 6.175 - parent changesets, and these become the parents of the new 6.176 - changeset.</para> 6.177 - 6.178 - <figure id="fig:tour-merge:merge"> 6.179 - <title>Working directory and repository during merge, and 6.180 - following commit</title> 6.181 - <mediaobject> 6.182 - <imageobject> 6.183 - <imagedata fileref="figs/tour-merge-merge.png"/> 6.184 - </imageobject> 6.185 - <textobject><phrase>XXX add text</phrase></textobject> 6.186 - </mediaobject> 6.187 - </figure> 6.188 - 6.189 - <para id="x_69c">We sometimes talk about a merge having 6.190 - <emphasis>sides</emphasis>: the left side is the first parent 6.191 - in the output of <command role="hg-cmd">hg parents</command>, 6.192 - and the right side is the second. If the working directory 6.193 - was at e.g. revision 5 before we began a merge, that revision 6.194 - will become the left side of the merge.</para> 6.195 - </sect2> 6.196 - </sect1> 6.197 - 6.198 - <sect1> 6.199 - <title>Merging conflicting changes</title> 6.200 - 6.201 - <para id="x_34b">Most merges are simple affairs, but sometimes you'll find 6.202 - yourself merging changes where each side modifies the same portions 6.203 - of the same files. Unless both modifications are identical, 6.204 - this results in a <emphasis>conflict</emphasis>, where you have 6.205 - to decide how to reconcile the different changes into something 6.206 - coherent.</para> 6.207 - 6.208 - <figure id="fig:tour-merge:conflict"> 6.209 - <title>Conflicting changes to a document</title> 6.210 - <mediaobject> 6.211 - <imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject> 6.212 - <textobject><phrase>XXX add text</phrase></textobject> 6.213 - </mediaobject> 6.214 - </figure> 6.215 - 6.216 - <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates 6.217 - an instance of two conflicting changes to a document. We 6.218 - started with a single version of the file; then we made some 6.219 - changes; while someone else made different changes to the same 6.220 - text. Our task in resolving the conflicting changes is to 6.221 - decide what the file should look like.</para> 6.222 - 6.223 - <para id="x_34e">Mercurial doesn't have a built-in facility for handling 6.224 - conflicts. Instead, it runs an external program, usually one 6.225 - that displays some kind of graphical conflict resolution 6.226 - interface. By default, Mercurial tries to find one of several 6.227 - different merging tools that are likely to be installed on your 6.228 - system. It first tries a few fully automatic merging tools; if 6.229 - these don't succeed (because the resolution process requires 6.230 - human guidance) or aren't present, it tries a few 6.231 - different graphical merging tools.</para> 6.232 - 6.233 - <para id="x_34f">It's also possible to get Mercurial to run a 6.234 - specific program or script, by setting the 6.235 - <envar>HGMERGE</envar> environment variable to the name of your 6.236 - preferred program.</para> 6.237 - 6.238 - <sect2> 6.239 - <title>Using a graphical merge tool</title> 6.240 - 6.241 - <para id="x_350">My preferred graphical merge tool is 6.242 - <command>kdiff3</command>, which I'll use to describe the 6.243 - features that are common to graphical file merging tools. You 6.244 - can see a screenshot of <command>kdiff3</command> in action in 6.245 - <xref linkend="fig:tour-merge:kdiff3"/>. The kind of 6.246 - merge it is performing is called a <emphasis>three-way 6.247 - merge</emphasis>, because there are three different versions 6.248 - of the file of interest to us. The tool thus splits the upper 6.249 - portion of the window into three panes:</para> 6.250 - <itemizedlist> 6.251 - <listitem><para id="x_351">At the left is the <emphasis>base</emphasis> 6.252 - version of the file, i.e. the most recent version from 6.253 - which the two versions we're trying to merge are 6.254 - descended.</para> 6.255 - </listitem> 6.256 - <listitem><para id="x_352">In the middle is <quote>our</quote> version of 6.257 - the file, with the contents that we modified.</para> 6.258 - </listitem> 6.259 - <listitem><para id="x_353">On the right is <quote>their</quote> version 6.260 - of the file, the one that from the changeset that we're 6.261 - trying to merge with.</para> 6.262 - </listitem></itemizedlist> 6.263 - <para id="x_354">In the pane below these is the current 6.264 - <emphasis>result</emphasis> of the merge. Our task is to 6.265 - replace all of the red text, which indicates unresolved 6.266 - conflicts, with some sensible merger of the 6.267 - <quote>ours</quote> and <quote>theirs</quote> versions of the 6.268 - file.</para> 6.269 - 6.270 - <para id="x_355">All four of these panes are <emphasis>locked 6.271 - together</emphasis>; if we scroll vertically or horizontally 6.272 - in any of them, the others are updated to display the 6.273 - corresponding sections of their respective files.</para> 6.274 - 6.275 - <figure id="fig:tour-merge:kdiff3"> 6.276 - <title>Using <command>kdiff3</command> to merge versions of a 6.277 - file</title> 6.278 - <mediaobject> 6.279 - <imageobject> 6.280 - <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject> 6.281 - <textobject> 6.282 - <phrase>XXX add text</phrase> 6.283 - </textobject> 6.284 - </mediaobject> 6.285 - </figure> 6.286 - 6.287 - <para id="x_357">For each conflicting portion of the file, we can choose to 6.288 - resolve the conflict using some combination of text from the 6.289 - base version, ours, or theirs. We can also manually edit the 6.290 - merged file at any time, in case we need to make further 6.291 - modifications.</para> 6.292 - 6.293 - <para id="x_358">There are <emphasis>many</emphasis> file merging tools 6.294 - available, too many to cover here. They vary in which 6.295 - platforms they are available for, and in their particular 6.296 - strengths and weaknesses. Most are tuned for merging files 6.297 - containing plain text, while a few are aimed at specialised 6.298 - file formats (generally XML).</para> 6.299 - </sect2> 6.300 - 6.301 - <sect2> 6.302 - <title>A worked example</title> 6.303 - 6.304 - <para id="x_359">In this example, we will reproduce the file modification 6.305 - history of <xref linkend="fig:tour-merge:conflict"/> 6.306 - above. Let's begin by creating a repository with a base 6.307 - version of our document.</para> 6.308 - 6.309 - &interaction.tour-merge-conflict.wife; 6.310 - 6.311 - <para id="x_35a">We'll clone the repository and make a change to the 6.312 - file.</para> 6.313 - 6.314 - &interaction.tour-merge-conflict.cousin; 6.315 - 6.316 - <para id="x_35b">And another clone, to simulate someone else making a 6.317 - change to the file. (This hints at the idea that it's not all 6.318 - that unusual to merge with yourself when you isolate tasks in 6.319 - separate repositories, and indeed to find and resolve 6.320 - conflicts while doing so.)</para> 6.321 - 6.322 - &interaction.tour-merge-conflict.son; 6.323 - 6.324 - <para id="x_35c">Having created two 6.325 - different versions of the file, we'll set up an environment 6.326 - suitable for running our merge.</para> 6.327 - 6.328 - &interaction.tour-merge-conflict.pull; 6.329 - 6.330 - <para id="x_35d">In this example, I'll set 6.331 - <envar>HGMERGE</envar> to tell Mercurial to use the 6.332 - non-interactive <command>merge</command> command. This is 6.333 - bundled with many Unix-like systems. (If you're following this 6.334 - example on your computer, don't bother setting 6.335 - <envar>HGMERGE</envar>. You'll get dropped into a GUI file 6.336 - merge tool instead, which is much preferable.)</para> 6.337 - 6.338 - &interaction.tour-merge-conflict.merge; 6.339 - 6.340 - <para id="x_35f">Because <command>merge</command> can't resolve the 6.341 - conflicting changes, it leaves <emphasis>merge 6.342 - markers</emphasis> inside the file that has conflicts, 6.343 - indicating which lines have conflicts, and whether they came 6.344 - from our version of the file or theirs.</para> 6.345 - 6.346 - <para id="x_360">Mercurial can tell from the way <command>merge</command> 6.347 - exits that it wasn't able to merge successfully, so it tells 6.348 - us what commands we'll need to run if we want to redo the 6.349 - merging operation. This could be useful if, for example, we 6.350 - were running a graphical merge tool and quit because we were 6.351 - confused or realised we had made a mistake.</para> 6.352 - 6.353 - <para id="x_361">If automatic or manual merges fail, there's nothing to 6.354 - prevent us from <quote>fixing up</quote> the affected files 6.355 - ourselves, and committing the results of our merge:</para> 6.356 - 6.357 - &interaction.tour-merge-conflict.commit; 6.358 - 6.359 - <note> 6.360 - <title>Where is the <command>hg resolve</command> command?</title> 6.361 - 6.362 - <para id="x_724">The <command>hg resolve</command> command was introduced 6.363 - in Mercurial 1.1, which was released in December 2008. If 6.364 - you are using an older version of Mercurial (run <command>hg 6.365 - version</command> to see), this command will not be 6.366 - present. If your version of Mercurial is older than 1.1, 6.367 - you should strongly consider upgrading to a newer version 6.368 - before trying to tackle complicated merges.</para> 6.369 - </note> 6.370 - </sect2> 6.371 - </sect1> 6.372 - 6.373 - <sect1 id="sec:tour-merge:fetch"> 6.374 - <title>Simplifying the pull-merge-commit sequence</title> 6.375 - 6.376 - <para id="x_362">The process of merging changes as outlined above is 6.377 - straightforward, but requires running three commands in 6.378 - sequence.</para> 6.379 - <programlisting>hg pull -u 6.380 -hg merge 6.381 -hg commit -m 'Merged remote changes'</programlisting> 6.382 - <para id="x_363">In the case of the final commit, you also need to enter a 6.383 - commit message, which is almost always going to be a piece of 6.384 - uninteresting <quote>boilerplate</quote> text.</para> 6.385 - 6.386 - <para id="x_364">It would be nice to reduce the number of steps needed, if 6.387 - this were possible. Indeed, Mercurial is distributed with an 6.388 - extension called <literal role="hg-ext">fetch</literal> that 6.389 - does just this.</para> 6.390 - 6.391 - <para id="x_365">Mercurial provides a flexible extension mechanism that lets 6.392 - people extend its functionality, while keeping the core of 6.393 - Mercurial small and easy to deal with. Some extensions add new 6.394 - commands that you can use from the command line, while others 6.395 - work <quote>behind the scenes,</quote> for example adding 6.396 - capabilities to Mercurial's built-in server mode.</para> 6.397 - 6.398 - <para id="x_366">The <literal role="hg-ext">fetch</literal> 6.399 - extension adds a new command called, not surprisingly, <command 6.400 - role="hg-cmd">hg fetch</command>. This extension acts as a 6.401 - combination of <command role="hg-cmd">hg pull -u</command>, 6.402 - <command role="hg-cmd">hg merge</command> and <command 6.403 - role="hg-cmd">hg commit</command>. It begins by pulling 6.404 - changes from another repository into the current repository. If 6.405 - it finds that the changes added a new head to the repository, it 6.406 - updates to the new head, begins a merge, then (if the merge 6.407 - succeeded) commits the result of the merge with an 6.408 - automatically-generated commit message. If no new heads were 6.409 - added, it updates the working directory to the new tip 6.410 - changeset.</para> 6.411 - 6.412 - <para id="x_367">Enabling the <literal 6.413 - role="hg-ext">fetch</literal> extension is easy. Edit the 6.414 - <filename role="special">.hgrc</filename> file in your home 6.415 - directory, and either go to the <literal 6.416 - role="rc-extensions">extensions</literal> section or create an 6.417 - <literal role="rc-extensions">extensions</literal> section. Then 6.418 - add a line that simply reads 6.419 - <quote><literal>fetch=</literal></quote>.</para> 6.420 - 6.421 - <programlisting>[extensions] 6.422 -fetch =</programlisting> 6.423 - 6.424 - <para id="x_368">(Normally, the right-hand side of the 6.425 - <quote><literal>=</literal></quote> would indicate where to find 6.426 - the extension, but since the <literal 6.427 - role="hg-ext">fetch</literal> extension is in the standard 6.428 - distribution, Mercurial knows where to search for it.)</para> 6.429 - </sect1> 6.430 - 6.431 - <sect1> 6.432 - <title>Renaming, copying, and merging</title> 6.433 - 6.434 - <para id="x_729">During the life of a project, we will often want to change 6.435 - the layout of its files and directories. This can be as simple 6.436 - as renaming a single file, or as complex as restructuring the 6.437 - entire hierarchy of files within the project.</para> 6.438 - 6.439 - <para id="x_72a">Mercurial supports these kinds of complex changes fluently, 6.440 - provided we tell it what we're doing. If we want to rename a 6.441 - file, we should use the <command>hg rename</command><footnote> 6.442 - <para id="x_72b">If you're a Unix user, you'll be glad to know that the 6.443 - <command>hg rename</command> command can be abbreviated as 6.444 - <command>hg mv</command>.</para> 6.445 - </footnote> command to rename it, so that Mercurial can do the 6.446 - right thing later when we merge.</para> 6.447 - 6.448 - <para id="x_72c">We will cover the use of these commands in more detail in 6.449 - <xref linkend="chap:daily.copy"/>.</para> 6.450 - </sect1> 6.451 -</chapter> 6.452 - 6.453 -<!-- 6.454 -local variables: 6.455 -sgml-parent-document: ("00book.xml" "book" "chapter") 6.456 -end: 6.457 --->
7.1 --- a/en/ch03-concepts.xml Thu May 07 21:06:49 2009 -0700 7.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 7.3 @@ -1,778 +0,0 @@ 7.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 7.5 - 7.6 -<chapter id="chap:concepts"> 7.7 - <?dbhtml filename="behind-the-scenes.html"?> 7.8 - <title>Behind the scenes</title> 7.9 - 7.10 - <para id="x_2e8">Unlike many revision control systems, the concepts 7.11 - upon which Mercurial is built are simple enough that it's easy to 7.12 - understand how the software really works. Knowing these details 7.13 - certainly isn't necessary, so it is certainly safe to skip this 7.14 - chapter. However, I think you will get more out of the software 7.15 - with a <quote>mental model</quote> of what's going on.</para> 7.16 - 7.17 - <para id="x_2e9">Being able to understand what's going on behind the 7.18 - scenes gives me confidence that Mercurial has been carefully 7.19 - designed to be both <emphasis>safe</emphasis> and 7.20 - <emphasis>efficient</emphasis>. And just as importantly, if it's 7.21 - easy for me to retain a good idea of what the software is doing 7.22 - when I perform a revision control task, I'm less likely to be 7.23 - surprised by its behavior.</para> 7.24 - 7.25 - <para id="x_2ea">In this chapter, we'll initially cover the core concepts 7.26 - behind Mercurial's design, then continue to discuss some of the 7.27 - interesting details of its implementation.</para> 7.28 - 7.29 - <sect1> 7.30 - <title>Mercurial's historical record</title> 7.31 - 7.32 - <sect2> 7.33 - <title>Tracking the history of a single file</title> 7.34 - 7.35 - <para id="x_2eb">When Mercurial tracks modifications to a file, it stores 7.36 - the history of that file in a metadata object called a 7.37 - <emphasis>filelog</emphasis>. Each entry in the filelog 7.38 - contains enough information to reconstruct one revision of the 7.39 - file that is being tracked. Filelogs are stored as files in 7.40 - the <filename role="special" 7.41 - class="directory">.hg/store/data</filename> directory. A 7.42 - filelog contains two kinds of information: revision data, and 7.43 - an index to help Mercurial to find a revision 7.44 - efficiently.</para> 7.45 - 7.46 - <para id="x_2ec">A file that is large, or has a lot of history, has its 7.47 - filelog stored in separate data 7.48 - (<quote><literal>.d</literal></quote> suffix) and index 7.49 - (<quote><literal>.i</literal></quote> suffix) files. For 7.50 - small files without much history, the revision data and index 7.51 - are combined in a single <quote><literal>.i</literal></quote> 7.52 - file. The correspondence between a file in the working 7.53 - directory and the filelog that tracks its history in the 7.54 - repository is illustrated in <xref 7.55 - linkend="fig:concepts:filelog"/>.</para> 7.56 - 7.57 - <figure id="fig:concepts:filelog"> 7.58 - <title>Relationships between files in working directory and 7.59 - filelogs in repository</title> 7.60 - <mediaobject> 7.61 - <imageobject><imagedata fileref="figs/filelog.png"/></imageobject> 7.62 - <textobject><phrase>XXX add text</phrase></textobject> 7.63 - </mediaobject> 7.64 - </figure> 7.65 - 7.66 - </sect2> 7.67 - <sect2> 7.68 - <title>Managing tracked files</title> 7.69 - 7.70 - <para id="x_2ee">Mercurial uses a structure called a 7.71 - <emphasis>manifest</emphasis> to collect together information 7.72 - about the files that it tracks. Each entry in the manifest 7.73 - contains information about the files present in a single 7.74 - changeset. An entry records which files are present in the 7.75 - changeset, the revision of each file, and a few other pieces 7.76 - of file metadata.</para> 7.77 - 7.78 - </sect2> 7.79 - <sect2> 7.80 - <title>Recording changeset information</title> 7.81 - 7.82 - <para id="x_2ef">The <emphasis>changelog</emphasis> contains information 7.83 - about each changeset. Each revision records who committed a 7.84 - change, the changeset comment, other pieces of 7.85 - changeset-related information, and the revision of the 7.86 - manifest to use.</para> 7.87 - 7.88 - </sect2> 7.89 - <sect2> 7.90 - <title>Relationships between revisions</title> 7.91 - 7.92 - <para id="x_2f0">Within a changelog, a manifest, or a filelog, each 7.93 - revision stores a pointer to its immediate parent (or to its 7.94 - two parents, if it's a merge revision). As I mentioned above, 7.95 - there are also relationships between revisions 7.96 - <emphasis>across</emphasis> these structures, and they are 7.97 - hierarchical in nature.</para> 7.98 - 7.99 - <para id="x_2f1">For every changeset in a repository, there is exactly one 7.100 - revision stored in the changelog. Each revision of the 7.101 - changelog contains a pointer to a single revision of the 7.102 - manifest. A revision of the manifest stores a pointer to a 7.103 - single revision of each filelog tracked when that changeset 7.104 - was created. These relationships are illustrated in 7.105 - <xref linkend="fig:concepts:metadata"/>.</para> 7.106 - 7.107 - <figure id="fig:concepts:metadata"> 7.108 - <title>Metadata relationships</title> 7.109 - <mediaobject> 7.110 - <imageobject><imagedata fileref="figs/metadata.png"/></imageobject> 7.111 - <textobject><phrase>XXX add text</phrase></textobject> 7.112 - </mediaobject> 7.113 - </figure> 7.114 - 7.115 - <para id="x_2f3">As the illustration shows, there is 7.116 - <emphasis>not</emphasis> a <quote>one to one</quote> 7.117 - relationship between revisions in the changelog, manifest, or 7.118 - filelog. If a file that 7.119 - Mercurial tracks hasn't changed between two changesets, the 7.120 - entry for that file in the two revisions of the manifest will 7.121 - point to the same revision of its filelog<footnote> 7.122 - <para id="x_725">It is possible (though unusual) for the manifest to 7.123 - remain the same between two changesets, in which case the 7.124 - changelog entries for those changesets will point to the 7.125 - same revision of the manifest.</para> 7.126 - </footnote>.</para> 7.127 - 7.128 - </sect2> 7.129 - </sect1> 7.130 - <sect1> 7.131 - <title>Safe, efficient storage</title> 7.132 - 7.133 - <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are 7.134 - provided by a single structure called the 7.135 - <emphasis>revlog</emphasis>.</para> 7.136 - 7.137 - <sect2> 7.138 - <title>Efficient storage</title> 7.139 - 7.140 - <para id="x_2f5">The revlog provides efficient storage of revisions using a 7.141 - <emphasis>delta</emphasis> mechanism. Instead of storing a 7.142 - complete copy of a file for each revision, it stores the 7.143 - changes needed to transform an older revision into the new 7.144 - revision. For many kinds of file data, these deltas are 7.145 - typically a fraction of a percent of the size of a full copy 7.146 - of a file.</para> 7.147 - 7.148 - <para id="x_2f6">Some obsolete revision control systems can only work with 7.149 - deltas of text files. They must either store binary files as 7.150 - complete snapshots or encoded into a text representation, both 7.151 - of which are wasteful approaches. Mercurial can efficiently 7.152 - handle deltas of files with arbitrary binary contents; it 7.153 - doesn't need to treat text as special.</para> 7.154 - 7.155 - </sect2> 7.156 - <sect2 id="sec:concepts:txn"> 7.157 - <title>Safe operation</title> 7.158 - 7.159 - <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to 7.160 - the end of a revlog file. It never modifies a section of a 7.161 - file after it has written it. This is both more robust and 7.162 - efficient than schemes that need to modify or rewrite 7.163 - data.</para> 7.164 - 7.165 - <para id="x_2f8">In addition, Mercurial treats every write as part of a 7.166 - <emphasis>transaction</emphasis> that can span a number of 7.167 - files. A transaction is <emphasis>atomic</emphasis>: either 7.168 - the entire transaction succeeds and its effects are all 7.169 - visible to readers in one go, or the whole thing is undone. 7.170 - This guarantee of atomicity means that if you're running two 7.171 - copies of Mercurial, where one is reading data and one is 7.172 - writing it, the reader will never see a partially written 7.173 - result that might confuse it.</para> 7.174 - 7.175 - <para id="x_2f9">The fact that Mercurial only appends to files makes it 7.176 - easier to provide this transactional guarantee. The easier it 7.177 - is to do stuff like this, the more confident you should be 7.178 - that it's done correctly.</para> 7.179 - 7.180 - </sect2> 7.181 - <sect2> 7.182 - <title>Fast retrieval</title> 7.183 - 7.184 - <para id="x_2fa">Mercurial cleverly avoids a pitfall common to 7.185 - all earlier revision control systems: the problem of 7.186 - <emphasis>inefficient retrieval</emphasis>. Most revision 7.187 - control systems store the contents of a revision as an 7.188 - incremental series of modifications against a 7.189 - <quote>snapshot</quote>. (Some base the snapshot on the 7.190 - oldest revision, others on the newest.) To reconstruct a 7.191 - specific revision, you must first read the snapshot, and then 7.192 - every one of the revisions between the snapshot and your 7.193 - target revision. The more history that a file accumulates, 7.194 - the more revisions you must read, hence the longer it takes to 7.195 - reconstruct a particular revision.</para> 7.196 - 7.197 - <figure id="fig:concepts:snapshot"> 7.198 - <title>Snapshot of a revlog, with incremental deltas</title> 7.199 - <mediaobject> 7.200 - <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject> 7.201 - <textobject><phrase>XXX add text</phrase></textobject> 7.202 - </mediaobject> 7.203 - </figure> 7.204 - 7.205 - <para id="x_2fc">The innovation that Mercurial applies to this problem is 7.206 - simple but effective. Once the cumulative amount of delta 7.207 - information stored since the last snapshot exceeds a fixed 7.208 - threshold, it stores a new snapshot (compressed, of course), 7.209 - instead of another delta. This makes it possible to 7.210 - reconstruct <emphasis>any</emphasis> revision of a file 7.211 - quickly. This approach works so well that it has since been 7.212 - copied by several other revision control systems.</para> 7.213 - 7.214 - <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates 7.215 - the idea. In an entry in a revlog's index file, Mercurial 7.216 - stores the range of entries from the data file that it must 7.217 - read to reconstruct a particular revision.</para> 7.218 - 7.219 - <sect3> 7.220 - <title>Aside: the influence of video compression</title> 7.221 - 7.222 - <para id="x_2fe">If you're familiar with video compression or 7.223 - have ever watched a TV feed through a digital cable or 7.224 - satellite service, you may know that most video compression 7.225 - schemes store each frame of video as a delta against its 7.226 - predecessor frame.</para> 7.227 - 7.228 - <para id="x_2ff">Mercurial borrows this idea to make it 7.229 - possible to reconstruct a revision from a snapshot and a 7.230 - small number of deltas.</para> 7.231 - 7.232 - </sect3> 7.233 - </sect2> 7.234 - <sect2> 7.235 - <title>Identification and strong integrity</title> 7.236 - 7.237 - <para id="x_300">Along with delta or snapshot information, a revlog entry 7.238 - contains a cryptographic hash of the data that it represents. 7.239 - This makes it difficult to forge the contents of a revision, 7.240 - and easy to detect accidental corruption.</para> 7.241 - 7.242 - <para id="x_301">Hashes provide more than a mere check against corruption; 7.243 - they are used as the identifiers for revisions. The changeset 7.244 - identification hashes that you see as an end user are from 7.245 - revisions of the changelog. Although filelogs and the 7.246 - manifest also use hashes, Mercurial only uses these behind the 7.247 - scenes.</para> 7.248 - 7.249 - <para id="x_302">Mercurial verifies that hashes are correct when it 7.250 - retrieves file revisions and when it pulls changes from 7.251 - another repository. If it encounters an integrity problem, it 7.252 - will complain and stop whatever it's doing.</para> 7.253 - 7.254 - <para id="x_303">In addition to the effect it has on retrieval efficiency, 7.255 - Mercurial's use of periodic snapshots makes it more robust 7.256 - against partial data corruption. If a revlog becomes partly 7.257 - corrupted due to a hardware error or system bug, it's often 7.258 - possible to reconstruct some or most revisions from the 7.259 - uncorrupted sections of the revlog, both before and after the 7.260 - corrupted section. This would not be possible with a 7.261 - delta-only storage model.</para> 7.262 - </sect2> 7.263 - </sect1> 7.264 - 7.265 - <sect1> 7.266 - <title>Revision history, branching, and merging</title> 7.267 - 7.268 - <para id="x_304">Every entry in a Mercurial revlog knows the identity of its 7.269 - immediate ancestor revision, usually referred to as its 7.270 - <emphasis>parent</emphasis>. In fact, a revision contains room 7.271 - for not one parent, but two. Mercurial uses a special hash, 7.272 - called the <quote>null ID</quote>, to represent the idea 7.273 - <quote>there is no parent here</quote>. This hash is simply a 7.274 - string of zeroes.</para> 7.275 - 7.276 - <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see 7.277 - an example of the conceptual structure of a revlog. Filelogs, 7.278 - manifests, and changelogs all have this same structure; they 7.279 - differ only in the kind of data stored in each delta or 7.280 - snapshot.</para> 7.281 - 7.282 - <para id="x_306">The first revision in a revlog (at the bottom of the image) 7.283 - has the null ID in both of its parent slots. For a 7.284 - <quote>normal</quote> revision, its first parent slot contains 7.285 - the ID of its parent revision, and its second contains the null 7.286 - ID, indicating that the revision has only one real parent. Any 7.287 - two revisions that have the same parent ID are branches. A 7.288 - revision that represents a merge between branches has two normal 7.289 - revision IDs in its parent slots.</para> 7.290 - 7.291 - <figure id="fig:concepts:revlog"> 7.292 - <title>The conceptual structure of a revlog</title> 7.293 - <mediaobject> 7.294 - <imageobject><imagedata fileref="figs/revlog.png"/></imageobject> 7.295 - <textobject><phrase>XXX add text</phrase></textobject> 7.296 - </mediaobject> 7.297 - </figure> 7.298 - 7.299 - </sect1> 7.300 - <sect1> 7.301 - <title>The working directory</title> 7.302 - 7.303 - <para id="x_307">In the working directory, Mercurial stores a snapshot of the 7.304 - files from the repository as of a particular changeset.</para> 7.305 - 7.306 - <para id="x_308">The working directory <quote>knows</quote> which changeset 7.307 - it contains. When you update the working directory to contain a 7.308 - particular changeset, Mercurial looks up the appropriate 7.309 - revision of the manifest to find out which files it was tracking 7.310 - at the time that changeset was committed, and which revision of 7.311 - each file was then current. It then recreates a copy of each of 7.312 - those files, with the same contents it had when the changeset 7.313 - was committed.</para> 7.314 - 7.315 - <para id="x_309">The <emphasis>dirstate</emphasis> is a special 7.316 - structure that contains Mercurial's knowledge of the working 7.317 - directory. It is maintained as a file named 7.318 - <filename>.hg/dirstate</filename> inside a repository. The 7.319 - dirstate details which changeset the working directory is 7.320 - updated to, and all of the files that Mercurial is tracking in 7.321 - the working directory. It also lets Mercurial quickly notice 7.322 - changed files, by recording their checkout times and 7.323 - sizes.</para> 7.324 - 7.325 - <para id="x_30a">Just as a revision of a revlog has room for two parents, so 7.326 - that it can represent either a normal revision (with one parent) 7.327 - or a merge of two earlier revisions, the dirstate has slots for 7.328 - two parents. When you use the <command role="hg-cmd">hg 7.329 - update</command> command, the changeset that you update to is 7.330 - stored in the <quote>first parent</quote> slot, and the null ID 7.331 - in the second. When you <command role="hg-cmd">hg 7.332 - merge</command> with another changeset, the first parent 7.333 - remains unchanged, and the second parent is filled in with the 7.334 - changeset you're merging with. The <command role="hg-cmd">hg 7.335 - parents</command> command tells you what the parents of the 7.336 - dirstate are.</para> 7.337 - 7.338 - <sect2> 7.339 - <title>What happens when you commit</title> 7.340 - 7.341 - <para id="x_30b">The dirstate stores parent information for more than just 7.342 - book-keeping purposes. Mercurial uses the parents of the 7.343 - dirstate as <emphasis>the parents of a new 7.344 - changeset</emphasis> when you perform a commit.</para> 7.345 - 7.346 - <figure id="fig:concepts:wdir"> 7.347 - <title>The working directory can have two parents</title> 7.348 - <mediaobject> 7.349 - <imageobject><imagedata fileref="figs/wdir.png"/></imageobject> 7.350 - <textobject><phrase>XXX add text</phrase></textobject> 7.351 - </mediaobject> 7.352 - </figure> 7.353 - 7.354 - <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the 7.355 - normal state of the working directory, where it has a single 7.356 - changeset as parent. That changeset is the 7.357 - <emphasis>tip</emphasis>, the newest changeset in the 7.358 - repository that has no children.</para> 7.359 - 7.360 - <figure id="fig:concepts:wdir-after-commit"> 7.361 - <title>The working directory gains new parents after a 7.362 - commit</title> 7.363 - <mediaobject> 7.364 - <imageobject><imagedata fileref="figs/wdir-after-commit.png"/></imageobject> 7.365 - <textobject><phrase>XXX add text</phrase></textobject> 7.366 - </mediaobject> 7.367 - </figure> 7.368 - 7.369 - <para id="x_30f">It's useful to think of the working directory as 7.370 - <quote>the changeset I'm about to commit</quote>. Any files 7.371 - that you tell Mercurial that you've added, removed, renamed, 7.372 - or copied will be reflected in that changeset, as will 7.373 - modifications to any files that Mercurial is already tracking; 7.374 - the new changeset will have the parents of the working 7.375 - directory as its parents.</para> 7.376 - 7.377 - <para id="x_310">After a commit, Mercurial will update the 7.378 - parents of the working directory, so that the first parent is 7.379 - the ID of the new changeset, and the second is the null ID. 7.380 - This is shown in <xref 7.381 - linkend="fig:concepts:wdir-after-commit"/>. Mercurial 7.382 - doesn't touch any of the files in the working directory when 7.383 - you commit; it just modifies the dirstate to note its new 7.384 - parents.</para> 7.385 - 7.386 - </sect2> 7.387 - <sect2> 7.388 - <title>Creating a new head</title> 7.389 - 7.390 - <para id="x_311">It's perfectly normal to update the working directory to a 7.391 - changeset other than the current tip. For example, you might 7.392 - want to know what your project looked like last Tuesday, or 7.393 - you could be looking through changesets to see which one 7.394 - introduced a bug. In cases like this, the natural thing to do 7.395 - is update the working directory to the changeset you're 7.396 - interested in, and then examine the files in the working 7.397 - directory directly to see their contents as they were when you 7.398 - committed that changeset. The effect of this is shown in 7.399 - <xref linkend="fig:concepts:wdir-pre-branch"/>.</para> 7.400 - 7.401 - <figure id="fig:concepts:wdir-pre-branch"> 7.402 - <title>The working directory, updated to an older 7.403 - changeset</title> 7.404 - <mediaobject> 7.405 - <imageobject><imagedata fileref="figs/wdir-pre-branch.png"/></imageobject> 7.406 - <textobject><phrase>XXX add text</phrase></textobject> 7.407 - </mediaobject> 7.408 - </figure> 7.409 - 7.410 - <para id="x_313">Having updated the working directory to an 7.411 - older changeset, what happens if you make some changes, and 7.412 - then commit? Mercurial behaves in the same way as I outlined 7.413 - above. The parents of the working directory become the 7.414 - parents of the new changeset. This new changeset has no 7.415 - children, so it becomes the new tip. And the repository now 7.416 - contains two changesets that have no children; we call these 7.417 - <emphasis>heads</emphasis>. You can see the structure that 7.418 - this creates in <xref 7.419 - linkend="fig:concepts:wdir-branch"/>.</para> 7.420 - 7.421 - <figure id="fig:concepts:wdir-branch"> 7.422 - <title>After a commit made while synced to an older 7.423 - changeset</title> 7.424 - <mediaobject> 7.425 - <imageobject><imagedata fileref="figs/wdir-branch.png"/></imageobject> 7.426 - <textobject><phrase>XXX add text</phrase></textobject> 7.427 - </mediaobject> 7.428 - </figure> 7.429 - 7.430 - <note> 7.431 - <para id="x_315">If you're new to Mercurial, you should keep 7.432 - in mind a common <quote>error</quote>, which is to use the 7.433 - <command role="hg-cmd">hg pull</command> command without any 7.434 - options. By default, the <command role="hg-cmd">hg 7.435 - pull</command> command <emphasis>does not</emphasis> 7.436 - update the working directory, so you'll bring new changesets 7.437 - into your repository, but the working directory will stay 7.438 - synced at the same changeset as before the pull. If you 7.439 - make some changes and commit afterwards, you'll thus create 7.440 - a new head, because your working directory isn't synced to 7.441 - whatever the current tip is. To combine the operation of a 7.442 - pull, followed by an update, run <command>hg pull 7.443 - -u</command>.</para> 7.444 - 7.445 - <para id="x_316">I put the word <quote>error</quote> in quotes 7.446 - because all that you need to do to rectify the situation 7.447 - where you created a new head by accident is 7.448 - <command role="hg-cmd">hg merge</command>, then <command 7.449 - role="hg-cmd">hg commit</command>. In other words, this 7.450 - almost never has negative consequences; it's just something 7.451 - of a surprise for newcomers. I'll discuss other ways to 7.452 - avoid this behavior, and why Mercurial behaves in this 7.453 - initially surprising way, later on.</para> 7.454 - </note> 7.455 - 7.456 - </sect2> 7.457 - <sect2> 7.458 - <title>Merging changes</title> 7.459 - 7.460 - <para id="x_317">When you run the <command role="hg-cmd">hg 7.461 - merge</command> command, Mercurial leaves the first parent 7.462 - of the working directory unchanged, and sets the second parent 7.463 - to the changeset you're merging with, as shown in <xref 7.464 - linkend="fig:concepts:wdir-merge"/>.</para> 7.465 - 7.466 - <figure id="fig:concepts:wdir-merge"> 7.467 - <title>Merging two heads</title> 7.468 - <mediaobject> 7.469 - <imageobject> 7.470 - <imagedata fileref="figs/wdir-merge.png"/> 7.471 - </imageobject> 7.472 - <textobject><phrase>XXX add text</phrase></textobject> 7.473 - </mediaobject> 7.474 - </figure> 7.475 - 7.476 - <para id="x_319">Mercurial also has to modify the working directory, to 7.477 - merge the files managed in the two changesets. Simplified a 7.478 - little, the merging process goes like this, for every file in 7.479 - the manifests of both changesets.</para> 7.480 - <itemizedlist> 7.481 - <listitem><para id="x_31a">If neither changeset has modified a file, do 7.482 - nothing with that file.</para> 7.483 - </listitem> 7.484 - <listitem><para id="x_31b">If one changeset has modified a file, and the 7.485 - other hasn't, create the modified copy of the file in the 7.486 - working directory.</para> 7.487 - </listitem> 7.488 - <listitem><para id="x_31c">If one changeset has removed a file, and the 7.489 - other hasn't (or has also deleted it), delete the file 7.490 - from the working directory.</para> 7.491 - </listitem> 7.492 - <listitem><para id="x_31d">If one changeset has removed a file, but the 7.493 - other has modified the file, ask the user what to do: keep 7.494 - the modified file, or remove it?</para> 7.495 - </listitem> 7.496 - <listitem><para id="x_31e">If both changesets have modified a file, 7.497 - invoke an external merge program to choose the new 7.498 - contents for the merged file. This may require input from 7.499 - the user.</para> 7.500 - </listitem> 7.501 - <listitem><para id="x_31f">If one changeset has modified a file, and the 7.502 - other has renamed or copied the file, make sure that the 7.503 - changes follow the new name of the file.</para> 7.504 - </listitem></itemizedlist> 7.505 - <para id="x_320">There are more details&emdash;merging has plenty of corner 7.506 - cases&emdash;but these are the most common choices that are 7.507 - involved in a merge. As you can see, most cases are 7.508 - completely automatic, and indeed most merges finish 7.509 - automatically, without requiring your input to resolve any 7.510 - conflicts.</para> 7.511 - 7.512 - <para id="x_321">When you're thinking about what happens when you commit 7.513 - after a merge, once again the working directory is <quote>the 7.514 - changeset I'm about to commit</quote>. After the <command 7.515 - role="hg-cmd">hg merge</command> command completes, the 7.516 - working directory has two parents; these will become the 7.517 - parents of the new changeset.</para> 7.518 - 7.519 - <para id="x_322">Mercurial lets you perform multiple merges, but 7.520 - you must commit the results of each individual merge as you 7.521 - go. This is necessary because Mercurial only tracks two 7.522 - parents for both revisions and the working directory. While 7.523 - it would be technically feasible to merge multiple changesets 7.524 - at once, Mercurial avoids this for simplicity. With multi-way 7.525 - merges, the risks of user confusion, nasty conflict 7.526 - resolution, and making a terrible mess of a merge would grow 7.527 - intolerable.</para> 7.528 - 7.529 - </sect2> 7.530 - 7.531 - <sect2> 7.532 - <title>Merging and renames</title> 7.533 - 7.534 - <para id="x_69a">A surprising number of revision control systems pay little 7.535 - or no attention to a file's <emphasis>name</emphasis> over 7.536 - time. For instance, it used to be common that if a file got 7.537 - renamed on one side of a merge, the changes from the other 7.538 - side would be silently dropped.</para> 7.539 - 7.540 - <para id="x_69b">Mercurial records metadata when you tell it to perform a 7.541 - rename or copy. It uses this metadata during a merge to do the 7.542 - right thing in the case of a merge. For instance, if I rename 7.543 - a file, and you edit it without renaming it, when we merge our 7.544 - work the file will be renamed and have your edits 7.545 - applied.</para> 7.546 - </sect2> 7.547 - </sect1> 7.548 - 7.549 - <sect1> 7.550 - <title>Other interesting design features</title> 7.551 - 7.552 - <para id="x_323">In the sections above, I've tried to highlight some of the 7.553 - most important aspects of Mercurial's design, to illustrate that 7.554 - it pays careful attention to reliability and performance. 7.555 - However, the attention to detail doesn't stop there. There are 7.556 - a number of other aspects of Mercurial's construction that I 7.557 - personally find interesting. I'll detail a few of them here, 7.558 - separate from the <quote>big ticket</quote> items above, so that 7.559 - if you're interested, you can gain a better idea of the amount 7.560 - of thinking that goes into a well-designed system.</para> 7.561 - 7.562 - <sect2> 7.563 - <title>Clever compression</title> 7.564 - 7.565 - <para id="x_324">When appropriate, Mercurial will store both snapshots and 7.566 - deltas in compressed form. It does this by always 7.567 - <emphasis>trying to</emphasis> compress a snapshot or delta, 7.568 - but only storing the compressed version if it's smaller than 7.569 - the uncompressed version.</para> 7.570 - 7.571 - <para id="x_325">This means that Mercurial does <quote>the right 7.572 - thing</quote> when storing a file whose native form is 7.573 - compressed, such as a <literal>zip</literal> archive or a JPEG 7.574 - image. When these types of files are compressed a second 7.575 - time, the resulting file is usually bigger than the 7.576 - once-compressed form, and so Mercurial will store the plain 7.577 - <literal>zip</literal> or JPEG.</para> 7.578 - 7.579 - <para id="x_326">Deltas between revisions of a compressed file are usually 7.580 - larger than snapshots of the file, and Mercurial again does 7.581 - <quote>the right thing</quote> in these cases. It finds that 7.582 - such a delta exceeds the threshold at which it should store a 7.583 - complete snapshot of the file, so it stores the snapshot, 7.584 - again saving space compared to a naive delta-only 7.585 - approach.</para> 7.586 - 7.587 - <sect3> 7.588 - <title>Network recompression</title> 7.589 - 7.590 - <para id="x_327">When storing revisions on disk, Mercurial uses the 7.591 - <quote>deflate</quote> compression algorithm (the same one 7.592 - used by the popular <literal>zip</literal> archive format), 7.593 - which balances good speed with a respectable compression 7.594 - ratio. However, when transmitting revision data over a 7.595 - network connection, Mercurial uncompresses the compressed 7.596 - revision data.</para> 7.597 - 7.598 - <para id="x_328">If the connection is over HTTP, Mercurial recompresses 7.599 - the entire stream of data using a compression algorithm that 7.600 - gives a better compression ratio (the Burrows-Wheeler 7.601 - algorithm from the widely used <literal>bzip2</literal> 7.602 - compression package). This combination of algorithm and 7.603 - compression of the entire stream (instead of a revision at a 7.604 - time) substantially reduces the number of bytes to be 7.605 - transferred, yielding better network performance over most 7.606 - kinds of network.</para> 7.607 - 7.608 - <para id="x_329">If the connection is over 7.609 - <command>ssh</command>, Mercurial 7.610 - <emphasis>doesn't</emphasis> recompress the stream, because 7.611 - <command>ssh</command> can already do this itself. You can 7.612 - tell Mercurial to always use <command>ssh</command>'s 7.613 - compression feature by editing the 7.614 - <filename>.hgrc</filename> file in your home directory as 7.615 - follows.</para> 7.616 - 7.617 - <programlisting>[ui] 7.618 -ssh = ssh -C</programlisting> 7.619 - 7.620 - </sect3> 7.621 - </sect2> 7.622 - <sect2> 7.623 - <title>Read/write ordering and atomicity</title> 7.624 - 7.625 - <para id="x_32a">Appending to files isn't the whole story when 7.626 - it comes to guaranteeing that a reader won't see a partial 7.627 - write. If you recall <xref linkend="fig:concepts:metadata"/>, 7.628 - revisions in the changelog point to revisions in the manifest, 7.629 - and revisions in the manifest point to revisions in filelogs. 7.630 - This hierarchy is deliberate.</para> 7.631 - 7.632 - <para id="x_32b">A writer starts a transaction by writing filelog and 7.633 - manifest data, and doesn't write any changelog data until 7.634 - those are finished. A reader starts by reading changelog 7.635 - data, then manifest data, followed by filelog data.</para> 7.636 - 7.637 - <para id="x_32c">Since the writer has always finished writing filelog and 7.638 - manifest data before it writes to the changelog, a reader will 7.639 - never read a pointer to a partially written manifest revision 7.640 - from the changelog, and it will never read a pointer to a 7.641 - partially written filelog revision from the manifest.</para> 7.642 - 7.643 - </sect2> 7.644 - <sect2> 7.645 - <title>Concurrent access</title> 7.646 - 7.647 - <para id="x_32d">The read/write ordering and atomicity guarantees mean that 7.648 - Mercurial never needs to <emphasis>lock</emphasis> a 7.649 - repository when it's reading data, even if the repository is 7.650 - being written to while the read is occurring. This has a big 7.651 - effect on scalability; you can have an arbitrary number of 7.652 - Mercurial processes safely reading data from a repository 7.653 - all at once, no matter whether it's being written to or 7.654 - not.</para> 7.655 - 7.656 - <para id="x_32e">The lockless nature of reading means that if you're 7.657 - sharing a repository on a multi-user system, you don't need to 7.658 - grant other local users permission to 7.659 - <emphasis>write</emphasis> to your repository in order for 7.660 - them to be able to clone it or pull changes from it; they only 7.661 - need <emphasis>read</emphasis> permission. (This is 7.662 - <emphasis>not</emphasis> a common feature among revision 7.663 - control systems, so don't take it for granted! Most require 7.664 - readers to be able to lock a repository to access it safely, 7.665 - and this requires write permission on at least one directory, 7.666 - which of course makes for all kinds of nasty and annoying 7.667 - security and administrative problems.)</para> 7.668 - 7.669 - <para id="x_32f">Mercurial uses locks to ensure that only one process can 7.670 - write to a repository at a time (the locking mechanism is safe 7.671 - even over filesystems that are notoriously hostile to locking, 7.672 - such as NFS). If a repository is locked, a writer will wait 7.673 - for a while to retry if the repository becomes unlocked, but 7.674 - if the repository remains locked for too long, the process 7.675 - attempting to write will time out after a while. This means 7.676 - that your daily automated scripts won't get stuck forever and 7.677 - pile up if a system crashes unnoticed, for example. (Yes, the 7.678 - timeout is configurable, from zero to infinity.)</para> 7.679 - 7.680 - <sect3> 7.681 - <title>Safe dirstate access</title> 7.682 - 7.683 - <para id="x_330">As with revision data, Mercurial doesn't take a lock to 7.684 - read the dirstate file; it does acquire a lock to write it. 7.685 - To avoid the possibility of reading a partially written copy 7.686 - of the dirstate file, Mercurial writes to a file with a 7.687 - unique name in the same directory as the dirstate file, then 7.688 - renames the temporary file atomically to 7.689 - <filename>dirstate</filename>. The file named 7.690 - <filename>dirstate</filename> is thus guaranteed to be 7.691 - complete, not partially written.</para> 7.692 - 7.693 - </sect3> 7.694 - </sect2> 7.695 - <sect2> 7.696 - <title>Avoiding seeks</title> 7.697 - 7.698 - <para id="x_331">Critical to Mercurial's performance is the avoidance of 7.699 - seeks of the disk head, since any seek is far more expensive 7.700 - than even a comparatively large read operation.</para> 7.701 - 7.702 - <para id="x_332">This is why, for example, the dirstate is stored in a 7.703 - single file. If there were a dirstate file per directory that 7.704 - Mercurial tracked, the disk would seek once per directory. 7.705 - Instead, Mercurial reads the entire single dirstate file in 7.706 - one step.</para> 7.707 - 7.708 - <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme 7.709 - when cloning a repository on local storage. Instead of 7.710 - copying every revlog file from the old repository into the new 7.711 - repository, it makes a <quote>hard link</quote>, which is a 7.712 - shorthand way to say <quote>these two names point to the same 7.713 - file</quote>. When Mercurial is about to write to one of a 7.714 - revlog's files, it checks to see if the number of names 7.715 - pointing at the file is greater than one. If it is, more than 7.716 - one repository is using the file, so Mercurial makes a new 7.717 - copy of the file that is private to this repository.</para> 7.718 - 7.719 - <para id="x_334">A few revision control developers have pointed out that 7.720 - this idea of making a complete private copy of a file is not 7.721 - very efficient in its use of storage. While this is true, 7.722 - storage is cheap, and this method gives the highest 7.723 - performance while deferring most book-keeping to the operating 7.724 - system. An alternative scheme would most likely reduce 7.725 - performance and increase the complexity of the software, but 7.726 - speed and simplicity are key to the <quote>feel</quote> of 7.727 - day-to-day use.</para> 7.728 - 7.729 - </sect2> 7.730 - <sect2> 7.731 - <title>Other contents of the dirstate</title> 7.732 - 7.733 - <para id="x_335">Because Mercurial doesn't force you to tell it when you're 7.734 - modifying a file, it uses the dirstate to store some extra 7.735 - information so it can determine efficiently whether you have 7.736 - modified a file. For each file in the working directory, it 7.737 - stores the time that it last modified the file itself, and the 7.738 - size of the file at that time.</para> 7.739 - 7.740 - <para id="x_336">When you explicitly <command role="hg-cmd">hg 7.741 - add</command>, <command role="hg-cmd">hg remove</command>, 7.742 - <command role="hg-cmd">hg rename</command> or <command 7.743 - role="hg-cmd">hg copy</command> files, Mercurial updates the 7.744 - dirstate so that it knows what to do with those files when you 7.745 - commit.</para> 7.746 - 7.747 - <para id="x_337">The dirstate helps Mercurial to efficiently 7.748 - check the status of files in a repository.</para> 7.749 - 7.750 - <itemizedlist> 7.751 - <listitem> 7.752 - <para id="x_726">When Mercurial checks the state of a file in the 7.753 - working directory, it first checks a file's modification 7.754 - time against the time in the dirstate that records when 7.755 - Mercurial last wrote the file. If the last modified time 7.756 - is the same as the time when Mercurial wrote the file, the 7.757 - file must not have been modified, so Mercurial does not 7.758 - need to check any further.</para> 7.759 - </listitem> 7.760 - <listitem> 7.761 - <para id="x_727">If the file's size has changed, the file must have 7.762 - been modified. If the modification time has changed, but 7.763 - the size has not, only then does Mercurial need to 7.764 - actually read the contents of the file to see if it has 7.765 - changed.</para> 7.766 - </listitem> 7.767 - </itemizedlist> 7.768 - 7.769 - <para id="x_728">Storing the modification time and size dramatically 7.770 - reduces the number of read operations that Mercurial needs to 7.771 - perform when we run commands like <command>hg status</command>. 7.772 - This results in large performance improvements.</para> 7.773 - </sect2> 7.774 - </sect1> 7.775 -</chapter> 7.776 - 7.777 -<!-- 7.778 -local variables: 7.779 -sgml-parent-document: ("00book.xml" "book" "chapter") 7.780 -end: 7.781 --->
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 8.2 +++ b/en/ch03-tour-merge.xml Thu May 07 21:07:35 2009 -0700 8.3 @@ -0,0 +1,454 @@ 8.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 8.5 + 8.6 +<chapter id="chap:tour-merge"> 8.7 + <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?> 8.8 + <title>A tour of Mercurial: merging work</title> 8.9 + 8.10 + <para id="x_338">We've now covered cloning a repository, making changes in a 8.11 + repository, and pulling or pushing changes from one repository 8.12 + into another. Our next step is <emphasis>merging</emphasis> 8.13 + changes from separate repositories.</para> 8.14 + 8.15 + <sect1> 8.16 + <title>Merging streams of work</title> 8.17 + 8.18 + <para id="x_339">Merging is a fundamental part of working with a distributed 8.19 + revision control tool. Here are a few cases in which the need 8.20 + to merge work arises.</para> 8.21 + <itemizedlist> 8.22 + <listitem> 8.23 + <para id="x_33a">Alice and Bob each have a personal copy of a 8.24 + repository for a project they're collaborating on. Alice 8.25 + fixes a bug in her repository; Bob adds a new feature in 8.26 + his. They want the shared repository to contain both the 8.27 + bug fix and the new feature.</para> 8.28 + </listitem> 8.29 + <listitem> 8.30 + <para id="x_33b">Cynthia frequently works on several different 8.31 + tasks for a single project at once, each safely isolated in 8.32 + its own repository. Working this way means that she often 8.33 + needs to merge one piece of her own work with 8.34 + another.</para> 8.35 + </listitem> 8.36 + </itemizedlist> 8.37 + 8.38 + <para id="x_33c">Because we need to merge often, Mercurial makes 8.39 + the process easy. Let's walk through a merge. We'll begin by 8.40 + cloning yet another repository (see how often they spring up?) 8.41 + and making a change in it.</para> 8.42 + 8.43 + &interaction.tour.merge.clone; 8.44 + 8.45 + <para id="x_33d">We should now have two copies of 8.46 + <filename>hello.c</filename> with different contents. The 8.47 + histories of the two repositories have also diverged, as 8.48 + illustrated in <xref 8.49 + linkend="fig:tour-merge:sep-repos"/>. Here is a copy of our 8.50 + file from one repository.</para> 8.51 + 8.52 + &interaction.tour.merge.cat1; 8.53 + 8.54 + <para id="x_722">And here is our slightly different version from the other 8.55 + repository.</para> 8.56 + 8.57 + &interaction.tour.merge.cat2; 8.58 + 8.59 + <figure id="fig:tour-merge:sep-repos"> 8.60 + <title>Divergent recent histories of the <filename 8.61 + class="directory">my-hello</filename> and <filename 8.62 + class="directory">my-new-hello</filename> 8.63 + repositories</title> 8.64 + <mediaobject> 8.65 + <imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject> 8.66 + <textobject><phrase>XXX add text</phrase></textobject> 8.67 + </mediaobject> 8.68 + </figure> 8.69 + 8.70 + <para id="x_33f">We already know that pulling changes from our <filename 8.71 + class="directory">my-hello</filename> repository will have no 8.72 + effect on the working directory.</para> 8.73 + 8.74 + &interaction.tour.merge.pull; 8.75 + 8.76 + <para id="x_340">However, the <command role="hg-cmd">hg pull</command> 8.77 + command says something about <quote>heads</quote>.</para> 8.78 + 8.79 + <sect2> 8.80 + <title>Head changesets</title> 8.81 + 8.82 + <para id="x_341">Remember that Mercurial records what the parent 8.83 + of each change is. If a change has a parent, we call it a 8.84 + child or descendant of the parent. A head is a change that 8.85 + has no children. The tip revision is thus a head, because the 8.86 + newest revision in a repository doesn't have any children. 8.87 + There are times when a repository can contain more than one 8.88 + head.</para> 8.89 + 8.90 + <figure id="fig:tour-merge:pull"> 8.91 + <title>Repository contents after pulling from <filename 8.92 + class="directory">my-hello</filename> into <filename 8.93 + class="directory">my-new-hello</filename></title> 8.94 + <mediaobject> 8.95 + <imageobject> 8.96 + <imagedata fileref="figs/tour-merge-pull.png"/> 8.97 + </imageobject> 8.98 + <textobject><phrase>XXX add text</phrase></textobject> 8.99 + </mediaobject> 8.100 + </figure> 8.101 + 8.102 + <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can 8.103 + see the effect of the pull from <filename 8.104 + class="directory">my-hello</filename> into <filename 8.105 + class="directory">my-new-hello</filename>. The history that 8.106 + was already present in <filename 8.107 + class="directory">my-new-hello</filename> is untouched, but 8.108 + a new revision has been added. By referring to <xref 8.109 + linkend="fig:tour-merge:sep-repos"/>, we can see that the 8.110 + <emphasis>changeset ID</emphasis> remains the same in the new 8.111 + repository, but the <emphasis>revision number</emphasis> has 8.112 + changed. (This, incidentally, is a fine example of why it's 8.113 + not safe to use revision numbers when discussing changesets.) 8.114 + We can view the heads in a repository using the <command 8.115 + role="hg-cmd">hg heads</command> command.</para> 8.116 + 8.117 + &interaction.tour.merge.heads; 8.118 + </sect2> 8.119 + 8.120 + <sect2> 8.121 + <title>Performing the merge</title> 8.122 + 8.123 + <para id="x_344">What happens if we try to use the normal <command 8.124 + role="hg-cmd">hg update</command> command to update to the 8.125 + new tip?</para> 8.126 + 8.127 + &interaction.tour.merge.update; 8.128 + 8.129 + <para id="x_345">Mercurial is telling us that the <command 8.130 + role="hg-cmd">hg update</command> command won't do a merge; 8.131 + it won't update the working directory when it thinks we might 8.132 + want to do a merge, unless we force it to do so. 8.133 + (Incidentally, forcing the update with <command>hg update 8.134 + -C</command> would revert any uncommitted changes in the 8.135 + working directory.)</para> 8.136 + 8.137 + <para id="x_723">To start a merge between the two heads, we use the 8.138 + <command role="hg-cmd">hg merge</command> command.</para> 8.139 + 8.140 + &interaction.tour.merge.merge; 8.141 + 8.142 + <para id="x_347">We resolve the contents of <filename>hello.c</filename> 8.143 + 8.144 +This updates the working directory so that it 8.145 + contains changes from <emphasis>both</emphasis> heads, which 8.146 + is reflected in both the output of <command role="hg-cmd">hg 8.147 + parents</command> and the contents of 8.148 + <filename>hello.c</filename>.</para> 8.149 + 8.150 + &interaction.tour.merge.parents; 8.151 + </sect2> 8.152 + 8.153 + <sect2> 8.154 + <title>Committing the results of the merge</title> 8.155 + 8.156 + <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg 8.157 + parents</command> will display two parents until we <command 8.158 + role="hg-cmd">hg commit</command> the results of the 8.159 + merge.</para> 8.160 + 8.161 + &interaction.tour.merge.commit; 8.162 + 8.163 + <para id="x_349">We now have a new tip revision; notice that it has 8.164 + <emphasis>both</emphasis> of our former heads as its parents. 8.165 + These are the same revisions that were previously displayed by 8.166 + <command role="hg-cmd">hg parents</command>.</para> 8.167 + 8.168 + &interaction.tour.merge.tip; 8.169 + 8.170 + <para id="x_34a">In <xref 8.171 + linkend="fig:tour-merge:merge"/>, you can see a 8.172 + representation of what happens to the working directory during 8.173 + the merge, and how this affects the repository when the commit 8.174 + happens. During the merge, the working directory has two 8.175 + parent changesets, and these become the parents of the new 8.176 + changeset.</para> 8.177 + 8.178 + <figure id="fig:tour-merge:merge"> 8.179 + <title>Working directory and repository during merge, and 8.180 + following commit</title> 8.181 + <mediaobject> 8.182 + <imageobject> 8.183 + <imagedata fileref="figs/tour-merge-merge.png"/> 8.184 + </imageobject> 8.185 + <textobject><phrase>XXX add text</phrase></textobject> 8.186 + </mediaobject> 8.187 + </figure> 8.188 + 8.189 + <para id="x_69c">We sometimes talk about a merge having 8.190 + <emphasis>sides</emphasis>: the left side is the first parent 8.191 + in the output of <command role="hg-cmd">hg parents</command>, 8.192 + and the right side is the second. If the working directory 8.193 + was at e.g. revision 5 before we began a merge, that revision 8.194 + will become the left side of the merge.</para> 8.195 + </sect2> 8.196 + </sect1> 8.197 + 8.198 + <sect1> 8.199 + <title>Merging conflicting changes</title> 8.200 + 8.201 + <para id="x_34b">Most merges are simple affairs, but sometimes you'll find 8.202 + yourself merging changes where each side modifies the same portions 8.203 + of the same files. Unless both modifications are identical, 8.204 + this results in a <emphasis>conflict</emphasis>, where you have 8.205 + to decide how to reconcile the different changes into something 8.206 + coherent.</para> 8.207 + 8.208 + <figure id="fig:tour-merge:conflict"> 8.209 + <title>Conflicting changes to a document</title> 8.210 + <mediaobject> 8.211 + <imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject> 8.212 + <textobject><phrase>XXX add text</phrase></textobject> 8.213 + </mediaobject> 8.214 + </figure> 8.215 + 8.216 + <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates 8.217 + an instance of two conflicting changes to a document. We 8.218 + started with a single version of the file; then we made some 8.219 + changes; while someone else made different changes to the same 8.220 + text. Our task in resolving the conflicting changes is to 8.221 + decide what the file should look like.</para> 8.222 + 8.223 + <para id="x_34e">Mercurial doesn't have a built-in facility for handling 8.224 + conflicts. Instead, it runs an external program, usually one 8.225 + that displays some kind of graphical conflict resolution 8.226 + interface. By default, Mercurial tries to find one of several 8.227 + different merging tools that are likely to be installed on your 8.228 + system. It first tries a few fully automatic merging tools; if 8.229 + these don't succeed (because the resolution process requires 8.230 + human guidance) or aren't present, it tries a few 8.231 + different graphical merging tools.</para> 8.232 + 8.233 + <para id="x_34f">It's also possible to get Mercurial to run a 8.234 + specific program or script, by setting the 8.235 + <envar>HGMERGE</envar> environment variable to the name of your 8.236 + preferred program.</para> 8.237 + 8.238 + <sect2> 8.239 + <title>Using a graphical merge tool</title> 8.240 + 8.241 + <para id="x_350">My preferred graphical merge tool is 8.242 + <command>kdiff3</command>, which I'll use to describe the 8.243 + features that are common to graphical file merging tools. You 8.244 + can see a screenshot of <command>kdiff3</command> in action in 8.245 + <xref linkend="fig:tour-merge:kdiff3"/>. The kind of 8.246 + merge it is performing is called a <emphasis>three-way 8.247 + merge</emphasis>, because there are three different versions 8.248 + of the file of interest to us. The tool thus splits the upper 8.249 + portion of the window into three panes:</para> 8.250 + <itemizedlist> 8.251 + <listitem><para id="x_351">At the left is the <emphasis>base</emphasis> 8.252 + version of the file, i.e. the most recent version from 8.253 + which the two versions we're trying to merge are 8.254 + descended.</para> 8.255 + </listitem> 8.256 + <listitem><para id="x_352">In the middle is <quote>our</quote> version of 8.257 + the file, with the contents that we modified.</para> 8.258 + </listitem> 8.259 + <listitem><para id="x_353">On the right is <quote>their</quote> version 8.260 + of the file, the one that from the changeset that we're 8.261 + trying to merge with.</para> 8.262 + </listitem></itemizedlist> 8.263 + <para id="x_354">In the pane below these is the current 8.264 + <emphasis>result</emphasis> of the merge. Our task is to 8.265 + replace all of the red text, which indicates unresolved 8.266 + conflicts, with some sensible merger of the 8.267 + <quote>ours</quote> and <quote>theirs</quote> versions of the 8.268 + file.</para> 8.269 + 8.270 + <para id="x_355">All four of these panes are <emphasis>locked 8.271 + together</emphasis>; if we scroll vertically or horizontally 8.272 + in any of them, the others are updated to display the 8.273 + corresponding sections of their respective files.</para> 8.274 + 8.275 + <figure id="fig:tour-merge:kdiff3"> 8.276 + <title>Using <command>kdiff3</command> to merge versions of a 8.277 + file</title> 8.278 + <mediaobject> 8.279 + <imageobject> 8.280 + <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject> 8.281 + <textobject> 8.282 + <phrase>XXX add text</phrase> 8.283 + </textobject> 8.284 + </mediaobject> 8.285 + </figure> 8.286 + 8.287 + <para id="x_357">For each conflicting portion of the file, we can choose to 8.288 + resolve the conflict using some combination of text from the 8.289 + base version, ours, or theirs. We can also manually edit the 8.290 + merged file at any time, in case we need to make further 8.291 + modifications.</para> 8.292 + 8.293 + <para id="x_358">There are <emphasis>many</emphasis> file merging tools 8.294 + available, too many to cover here. They vary in which 8.295 + platforms they are available for, and in their particular 8.296 + strengths and weaknesses. Most are tuned for merging files 8.297 + containing plain text, while a few are aimed at specialised 8.298 + file formats (generally XML).</para> 8.299 + </sect2> 8.300 + 8.301 + <sect2> 8.302 + <title>A worked example</title> 8.303 + 8.304 + <para id="x_359">In this example, we will reproduce the file modification 8.305 + history of <xref linkend="fig:tour-merge:conflict"/> 8.306 + above. Let's begin by creating a repository with a base 8.307 + version of our document.</para> 8.308 + 8.309 + &interaction.tour-merge-conflict.wife; 8.310 + 8.311 + <para id="x_35a">We'll clone the repository and make a change to the 8.312 + file.</para> 8.313 + 8.314 + &interaction.tour-merge-conflict.cousin; 8.315 + 8.316 + <para id="x_35b">And another clone, to simulate someone else making a 8.317 + change to the file. (This hints at the idea that it's not all 8.318 + that unusual to merge with yourself when you isolate tasks in 8.319 + separate repositories, and indeed to find and resolve 8.320 + conflicts while doing so.)</para> 8.321 + 8.322 + &interaction.tour-merge-conflict.son; 8.323 + 8.324 + <para id="x_35c">Having created two 8.325 + different versions of the file, we'll set up an environment 8.326 + suitable for running our merge.</para> 8.327 + 8.328 + &interaction.tour-merge-conflict.pull; 8.329 + 8.330 + <para id="x_35d">In this example, I'll set 8.331 + <envar>HGMERGE</envar> to tell Mercurial to use the 8.332 + non-interactive <command>merge</command> command. This is 8.333 + bundled with many Unix-like systems. (If you're following this 8.334 + example on your computer, don't bother setting 8.335 + <envar>HGMERGE</envar>. You'll get dropped into a GUI file 8.336 + merge tool instead, which is much preferable.)</para> 8.337 + 8.338 + &interaction.tour-merge-conflict.merge; 8.339 + 8.340 + <para id="x_35f">Because <command>merge</command> can't resolve the 8.341 + conflicting changes, it leaves <emphasis>merge 8.342 + markers</emphasis> inside the file that has conflicts, 8.343 + indicating which lines have conflicts, and whether they came 8.344 + from our version of the file or theirs.</para> 8.345 + 8.346 + <para id="x_360">Mercurial can tell from the way <command>merge</command> 8.347 + exits that it wasn't able to merge successfully, so it tells 8.348 + us what commands we'll need to run if we want to redo the 8.349 + merging operation. This could be useful if, for example, we 8.350 + were running a graphical merge tool and quit because we were 8.351 + confused or realised we had made a mistake.</para> 8.352 + 8.353 + <para id="x_361">If automatic or manual merges fail, there's nothing to 8.354 + prevent us from <quote>fixing up</quote> the affected files 8.355 + ourselves, and committing the results of our merge:</para> 8.356 + 8.357 + &interaction.tour-merge-conflict.commit; 8.358 + 8.359 + <note> 8.360 + <title>Where is the <command>hg resolve</command> command?</title> 8.361 + 8.362 + <para id="x_724">The <command>hg resolve</command> command was introduced 8.363 + in Mercurial 1.1, which was released in December 2008. If 8.364 + you are using an older version of Mercurial (run <command>hg 8.365 + version</command> to see), this command will not be 8.366 + present. If your version of Mercurial is older than 1.1, 8.367 + you should strongly consider upgrading to a newer version 8.368 + before trying to tackle complicated merges.</para> 8.369 + </note> 8.370 + </sect2> 8.371 + </sect1> 8.372 + 8.373 + <sect1 id="sec:tour-merge:fetch"> 8.374 + <title>Simplifying the pull-merge-commit sequence</title> 8.375 + 8.376 + <para id="x_362">The process of merging changes as outlined above is 8.377 + straightforward, but requires running three commands in 8.378 + sequence.</para> 8.379 + <programlisting>hg pull -u 8.380 +hg merge 8.381 +hg commit -m 'Merged remote changes'</programlisting> 8.382 + <para id="x_363">In the case of the final commit, you also need to enter a 8.383 + commit message, which is almost always going to be a piece of 8.384 + uninteresting <quote>boilerplate</quote> text.</para> 8.385 + 8.386 + <para id="x_364">It would be nice to reduce the number of steps needed, if 8.387 + this were possible. Indeed, Mercurial is distributed with an 8.388 + extension called <literal role="hg-ext">fetch</literal> that 8.389 + does just this.</para> 8.390 + 8.391 + <para id="x_365">Mercurial provides a flexible extension mechanism that lets 8.392 + people extend its functionality, while keeping the core of 8.393 + Mercurial small and easy to deal with. Some extensions add new 8.394 + commands that you can use from the command line, while others 8.395 + work <quote>behind the scenes,</quote> for example adding 8.396 + capabilities to Mercurial's built-in server mode.</para> 8.397 + 8.398 + <para id="x_366">The <literal role="hg-ext">fetch</literal> 8.399 + extension adds a new command called, not surprisingly, <command 8.400 + role="hg-cmd">hg fetch</command>. This extension acts as a 8.401 + combination of <command role="hg-cmd">hg pull -u</command>, 8.402 + <command role="hg-cmd">hg merge</command> and <command 8.403 + role="hg-cmd">hg commit</command>. It begins by pulling 8.404 + changes from another repository into the current repository. If 8.405 + it finds that the changes added a new head to the repository, it 8.406 + updates to the new head, begins a merge, then (if the merge 8.407 + succeeded) commits the result of the merge with an 8.408 + automatically-generated commit message. If no new heads were 8.409 + added, it updates the working directory to the new tip 8.410 + changeset.</para> 8.411 + 8.412 + <para id="x_367">Enabling the <literal 8.413 + role="hg-ext">fetch</literal> extension is easy. Edit the 8.414 + <filename role="special">.hgrc</filename> file in your home 8.415 + directory, and either go to the <literal 8.416 + role="rc-extensions">extensions</literal> section or create an 8.417 + <literal role="rc-extensions">extensions</literal> section. Then 8.418 + add a line that simply reads 8.419 + <quote><literal>fetch=</literal></quote>.</para> 8.420 + 8.421 + <programlisting>[extensions] 8.422 +fetch =</programlisting> 8.423 + 8.424 + <para id="x_368">(Normally, the right-hand side of the 8.425 + <quote><literal>=</literal></quote> would indicate where to find 8.426 + the extension, but since the <literal 8.427 + role="hg-ext">fetch</literal> extension is in the standard 8.428 + distribution, Mercurial knows where to search for it.)</para> 8.429 + </sect1> 8.430 + 8.431 + <sect1> 8.432 + <title>Renaming, copying, and merging</title> 8.433 + 8.434 + <para id="x_729">During the life of a project, we will often want to change 8.435 + the layout of its files and directories. This can be as simple 8.436 + as renaming a single file, or as complex as restructuring the 8.437 + entire hierarchy of files within the project.</para> 8.438 + 8.439 + <para id="x_72a">Mercurial supports these kinds of complex changes fluently, 8.440 + provided we tell it what we're doing. If we want to rename a 8.441 + file, we should use the <command>hg rename</command><footnote> 8.442 + <para id="x_72b">If you're a Unix user, you'll be glad to know that the 8.443 + <command>hg rename</command> command can be abbreviated as 8.444 + <command>hg mv</command>.</para> 8.445 + </footnote> command to rename it, so that Mercurial can do the 8.446 + right thing later when we merge.</para> 8.447 + 8.448 + <para id="x_72c">We will cover the use of these commands in more detail in 8.449 + <xref linkend="chap:daily.copy"/>.</para> 8.450 + </sect1> 8.451 +</chapter> 8.452 + 8.453 +<!-- 8.454 +local variables: 8.455 +sgml-parent-document: ("00book.xml" "book" "chapter") 8.456 +end: 8.457 +-->
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 9.2 +++ b/en/ch04-concepts.xml Thu May 07 21:07:35 2009 -0700 9.3 @@ -0,0 +1,778 @@ 9.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 9.5 + 9.6 +<chapter id="chap:concepts"> 9.7 + <?dbhtml filename="behind-the-scenes.html"?> 9.8 + <title>Behind the scenes</title> 9.9 + 9.10 + <para id="x_2e8">Unlike many revision control systems, the concepts 9.11 + upon which Mercurial is built are simple enough that it's easy to 9.12 + understand how the software really works. Knowing these details 9.13 + certainly isn't necessary, so it is certainly safe to skip this 9.14 + chapter. However, I think you will get more out of the software 9.15 + with a <quote>mental model</quote> of what's going on.</para> 9.16 + 9.17 + <para id="x_2e9">Being able to understand what's going on behind the 9.18 + scenes gives me confidence that Mercurial has been carefully 9.19 + designed to be both <emphasis>safe</emphasis> and 9.20 + <emphasis>efficient</emphasis>. And just as importantly, if it's 9.21 + easy for me to retain a good idea of what the software is doing 9.22 + when I perform a revision control task, I'm less likely to be 9.23 + surprised by its behavior.</para> 9.24 + 9.25 + <para id="x_2ea">In this chapter, we'll initially cover the core concepts 9.26 + behind Mercurial's design, then continue to discuss some of the 9.27 + interesting details of its implementation.</para> 9.28 + 9.29 + <sect1> 9.30 + <title>Mercurial's historical record</title> 9.31 + 9.32 + <sect2> 9.33 + <title>Tracking the history of a single file</title> 9.34 + 9.35 + <para id="x_2eb">When Mercurial tracks modifications to a file, it stores 9.36 + the history of that file in a metadata object called a 9.37 + <emphasis>filelog</emphasis>. Each entry in the filelog 9.38 + contains enough information to reconstruct one revision of the 9.39 + file that is being tracked. Filelogs are stored as files in 9.40 + the <filename role="special" 9.41 + class="directory">.hg/store/data</filename> directory. A 9.42 + filelog contains two kinds of information: revision data, and 9.43 + an index to help Mercurial to find a revision 9.44 + efficiently.</para> 9.45 + 9.46 + <para id="x_2ec">A file that is large, or has a lot of history, has its 9.47 + filelog stored in separate data 9.48 + (<quote><literal>.d</literal></quote> suffix) and index 9.49 + (<quote><literal>.i</literal></quote> suffix) files. For 9.50 + small files without much history, the revision data and index 9.51 + are combined in a single <quote><literal>.i</literal></quote> 9.52 + file. The correspondence between a file in the working 9.53 + directory and the filelog that tracks its history in the 9.54 + repository is illustrated in <xref 9.55 + linkend="fig:concepts:filelog"/>.</para> 9.56 + 9.57 + <figure id="fig:concepts:filelog"> 9.58 + <title>Relationships between files in working directory and 9.59 + filelogs in repository</title> 9.60 + <mediaobject> 9.61 + <imageobject><imagedata fileref="figs/filelog.png"/></imageobject> 9.62 + <textobject><phrase>XXX add text</phrase></textobject> 9.63 + </mediaobject> 9.64 + </figure> 9.65 + 9.66 + </sect2> 9.67 + <sect2> 9.68 + <title>Managing tracked files</title> 9.69 + 9.70 + <para id="x_2ee">Mercurial uses a structure called a 9.71 + <emphasis>manifest</emphasis> to collect together information 9.72 + about the files that it tracks. Each entry in the manifest 9.73 + contains information about the files present in a single 9.74 + changeset. An entry records which files are present in the 9.75 + changeset, the revision of each file, and a few other pieces 9.76 + of file metadata.</para> 9.77 + 9.78 + </sect2> 9.79 + <sect2> 9.80 + <title>Recording changeset information</title> 9.81 + 9.82 + <para id="x_2ef">The <emphasis>changelog</emphasis> contains information 9.83 + about each changeset. Each revision records who committed a 9.84 + change, the changeset comment, other pieces of 9.85 + changeset-related information, and the revision of the 9.86 + manifest to use.</para> 9.87 + 9.88 + </sect2> 9.89 + <sect2> 9.90 + <title>Relationships between revisions</title> 9.91 + 9.92 + <para id="x_2f0">Within a changelog, a manifest, or a filelog, each 9.93 + revision stores a pointer to its immediate parent (or to its 9.94 + two parents, if it's a merge revision). As I mentioned above, 9.95 + there are also relationships between revisions 9.96 + <emphasis>across</emphasis> these structures, and they are 9.97 + hierarchical in nature.</para> 9.98 + 9.99 + <para id="x_2f1">For every changeset in a repository, there is exactly one 9.100 + revision stored in the changelog. Each revision of the 9.101 + changelog contains a pointer to a single revision of the 9.102 + manifest. A revision of the manifest stores a pointer to a 9.103 + single revision of each filelog tracked when that changeset 9.104 + was created. These relationships are illustrated in 9.105 + <xref linkend="fig:concepts:metadata"/>.</para> 9.106 + 9.107 + <figure id="fig:concepts:metadata"> 9.108 + <title>Metadata relationships</title> 9.109 + <mediaobject> 9.110 + <imageobject><imagedata fileref="figs/metadata.png"/></imageobject> 9.111 + <textobject><phrase>XXX add text</phrase></textobject> 9.112 + </mediaobject> 9.113 + </figure> 9.114 + 9.115 + <para id="x_2f3">As the illustration shows, there is 9.116 + <emphasis>not</emphasis> a <quote>one to one</quote> 9.117 + relationship between revisions in the changelog, manifest, or 9.118 + filelog. If a file that 9.119 + Mercurial tracks hasn't changed between two changesets, the 9.120 + entry for that file in the two revisions of the manifest will 9.121 + point to the same revision of its filelog<footnote> 9.122 + <para id="x_725">It is possible (though unusual) for the manifest to 9.123 + remain the same between two changesets, in which case the 9.124 + changelog entries for those changesets will point to the 9.125 + same revision of the manifest.</para> 9.126 + </footnote>.</para> 9.127 + 9.128 + </sect2> 9.129 + </sect1> 9.130 + <sect1> 9.131 + <title>Safe, efficient storage</title> 9.132 + 9.133 + <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are 9.134 + provided by a single structure called the 9.135 + <emphasis>revlog</emphasis>.</para> 9.136 + 9.137 + <sect2> 9.138 + <title>Efficient storage</title> 9.139 + 9.140 + <para id="x_2f5">The revlog provides efficient storage of revisions using a 9.141 + <emphasis>delta</emphasis> mechanism. Instead of storing a 9.142 + complete copy of a file for each revision, it stores the 9.143 + changes needed to transform an older revision into the new 9.144 + revision. For many kinds of file data, these deltas are 9.145 + typically a fraction of a percent of the size of a full copy 9.146 + of a file.</para> 9.147 + 9.148 + <para id="x_2f6">Some obsolete revision control systems can only work with 9.149 + deltas of text files. They must either store binary files as 9.150 + complete snapshots or encoded into a text representation, both 9.151 + of which are wasteful approaches. Mercurial can efficiently 9.152 + handle deltas of files with arbitrary binary contents; it 9.153 + doesn't need to treat text as special.</para> 9.154 + 9.155 + </sect2> 9.156 + <sect2 id="sec:concepts:txn"> 9.157 + <title>Safe operation</title> 9.158 + 9.159 + <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to 9.160 + the end of a revlog file. It never modifies a section of a 9.161 + file after it has written it. This is both more robust and 9.162 + efficient than schemes that need to modify or rewrite 9.163 + data.</para> 9.164 + 9.165 + <para id="x_2f8">In addition, Mercurial treats every write as part of a 9.166 + <emphasis>transaction</emphasis> that can span a number of 9.167 + files. A transaction is <emphasis>atomic</emphasis>: either 9.168 + the entire transaction succeeds and its effects are all 9.169 + visible to readers in one go, or the whole thing is undone. 9.170 + This guarantee of atomicity means that if you're running two 9.171 + copies of Mercurial, where one is reading data and one is 9.172 + writing it, the reader will never see a partially written 9.173 + result that might confuse it.</para> 9.174 + 9.175 + <para id="x_2f9">The fact that Mercurial only appends to files makes it 9.176 + easier to provide this transactional guarantee. The easier it 9.177 + is to do stuff like this, the more confident you should be 9.178 + that it's done correctly.</para> 9.179 + 9.180 + </sect2> 9.181 + <sect2> 9.182 + <title>Fast retrieval</title> 9.183 + 9.184 + <para id="x_2fa">Mercurial cleverly avoids a pitfall common to 9.185 + all earlier revision control systems: the problem of 9.186 + <emphasis>inefficient retrieval</emphasis>. Most revision 9.187 + control systems store the contents of a revision as an 9.188 + incremental series of modifications against a 9.189 + <quote>snapshot</quote>. (Some base the snapshot on the 9.190 + oldest revision, others on the newest.) To reconstruct a 9.191 + specific revision, you must first read the snapshot, and then 9.192 + every one of the revisions between the snapshot and your 9.193 + target revision. The more history that a file accumulates, 9.194 + the more revisions you must read, hence the longer it takes to 9.195 + reconstruct a particular revision.</para> 9.196 + 9.197 + <figure id="fig:concepts:snapshot"> 9.198 + <title>Snapshot of a revlog, with incremental deltas</title> 9.199 + <mediaobject> 9.200 + <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject> 9.201 + <textobject><phrase>XXX add text</phrase></textobject> 9.202 + </mediaobject> 9.203 + </figure> 9.204 + 9.205 + <para id="x_2fc">The innovation that Mercurial applies to this problem is 9.206 + simple but effective. Once the cumulative amount of delta 9.207 + information stored since the last snapshot exceeds a fixed 9.208 + threshold, it stores a new snapshot (compressed, of course), 9.209 + instead of another delta. This makes it possible to 9.210 + reconstruct <emphasis>any</emphasis> revision of a file 9.211 + quickly. This approach works so well that it has since been 9.212 + copied by several other revision control systems.</para> 9.213 + 9.214 + <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates 9.215 + the idea. In an entry in a revlog's index file, Mercurial 9.216 + stores the range of entries from the data file that it must 9.217 + read to reconstruct a particular revision.</para> 9.218 + 9.219 + <sect3> 9.220 + <title>Aside: the influence of video compression</title> 9.221 + 9.222 + <para id="x_2fe">If you're familiar with video compression or 9.223 + have ever watched a TV feed through a digital cable or 9.224 + satellite service, you may know that most video compression 9.225 + schemes store each frame of video as a delta against its 9.226 + predecessor frame.</para> 9.227 + 9.228 + <para id="x_2ff">Mercurial borrows this idea to make it 9.229 + possible to reconstruct a revision from a snapshot and a 9.230 + small number of deltas.</para> 9.231 + 9.232 + </sect3> 9.233 + </sect2> 9.234 + <sect2> 9.235 + <title>Identification and strong integrity</title> 9.236 + 9.237 + <para id="x_300">Along with delta or snapshot information, a revlog entry 9.238 + contains a cryptographic hash of the data that it represents. 9.239 + This makes it difficult to forge the contents of a revision, 9.240 + and easy to detect accidental corruption.</para> 9.241 + 9.242 + <para id="x_301">Hashes provide more than a mere check against corruption; 9.243 + they are used as the identifiers for revisions. The changeset 9.244 + identification hashes that you see as an end user are from 9.245 + revisions of the changelog. Although filelogs and the 9.246 + manifest also use hashes, Mercurial only uses these behind the 9.247 + scenes.</para> 9.248 + 9.249 + <para id="x_302">Mercurial verifies that hashes are correct when it 9.250 + retrieves file revisions and when it pulls changes from 9.251 + another repository. If it encounters an integrity problem, it 9.252 + will complain and stop whatever it's doing.</para> 9.253 + 9.254 + <para id="x_303">In addition to the effect it has on retrieval efficiency, 9.255 + Mercurial's use of periodic snapshots makes it more robust 9.256 + against partial data corruption. If a revlog becomes partly 9.257 + corrupted due to a hardware error or system bug, it's often 9.258 + possible to reconstruct some or most revisions from the 9.259 + uncorrupted sections of the revlog, both before and after the 9.260 + corrupted section. This would not be possible with a 9.261 + delta-only storage model.</para> 9.262 + </sect2> 9.263 + </sect1> 9.264 + 9.265 + <sect1> 9.266 + <title>Revision history, branching, and merging</title> 9.267 + 9.268 + <para id="x_304">Every entry in a Mercurial revlog knows the identity of its 9.269 + immediate ancestor revision, usually referred to as its 9.270 + <emphasis>parent</emphasis>. In fact, a revision contains room 9.271 + for not one parent, but two. Mercurial uses a special hash, 9.272 + called the <quote>null ID</quote>, to represent the idea 9.273 + <quote>there is no parent here</quote>. This hash is simply a 9.274 + string of zeroes.</para> 9.275 + 9.276 + <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see 9.277 + an example of the conceptual structure of a revlog. Filelogs, 9.278 + manifests, and changelogs all have this same structure; they 9.279 + differ only in the kind of data stored in each delta or 9.280 + snapshot.</para> 9.281 + 9.282 + <para id="x_306">The first revision in a revlog (at the bottom of the image) 9.283 + has the null ID in both of its parent slots. For a 9.284 + <quote>normal</quote> revision, its first parent slot contains 9.285 + the ID of its parent revision, and its second contains the null 9.286 + ID, indicating that the revision has only one real parent. Any 9.287 + two revisions that have the same parent ID are branches. A 9.288 + revision that represents a merge between branches has two normal 9.289 + revision IDs in its parent slots.</para> 9.290 + 9.291 + <figure id="fig:concepts:revlog"> 9.292 + <title>The conceptual structure of a revlog</title> 9.293 + <mediaobject> 9.294 + <imageobject><imagedata fileref="figs/revlog.png"/></imageobject> 9.295 + <textobject><phrase>XXX add text</phrase></textobject> 9.296 + </mediaobject> 9.297 + </figure> 9.298 + 9.299 + </sect1> 9.300 + <sect1> 9.301 + <title>The working directory</title> 9.302 + 9.303 + <para id="x_307">In the working directory, Mercurial stores a snapshot of the 9.304 + files from the repository as of a particular changeset.</para> 9.305 + 9.306 + <para id="x_308">The working directory <quote>knows</quote> which changeset 9.307 + it contains. When you update the working directory to contain a 9.308 + particular changeset, Mercurial looks up the appropriate 9.309 + revision of the manifest to find out which files it was tracking 9.310 + at the time that changeset was committed, and which revision of 9.311 + each file was then current. It then recreates a copy of each of 9.312 + those files, with the same contents it had when the changeset 9.313 + was committed.</para> 9.314 + 9.315 + <para id="x_309">The <emphasis>dirstate</emphasis> is a special 9.316 + structure that contains Mercurial's knowledge of the working 9.317 + directory. It is maintained as a file named 9.318 + <filename>.hg/dirstate</filename> inside a repository. The 9.319 + dirstate details which changeset the working directory is 9.320 + updated to, and all of the files that Mercurial is tracking in 9.321 + the working directory. It also lets Mercurial quickly notice 9.322 + changed files, by recording their checkout times and 9.323 + sizes.</para> 9.324 + 9.325 + <para id="x_30a">Just as a revision of a revlog has room for two parents, so 9.326 + that it can represent either a normal revision (with one parent) 9.327 + or a merge of two earlier revisions, the dirstate has slots for 9.328 + two parents. When you use the <command role="hg-cmd">hg 9.329 + update</command> command, the changeset that you update to is 9.330 + stored in the <quote>first parent</quote> slot, and the null ID 9.331 + in the second. When you <command role="hg-cmd">hg 9.332 + merge</command> with another changeset, the first parent 9.333 + remains unchanged, and the second parent is filled in with the 9.334 + changeset you're merging with. The <command role="hg-cmd">hg 9.335 + parents</command> command tells you what the parents of the 9.336 + dirstate are.</para> 9.337 + 9.338 + <sect2> 9.339 + <title>What happens when you commit</title> 9.340 + 9.341 + <para id="x_30b">The dirstate stores parent information for more than just 9.342 + book-keeping purposes. Mercurial uses the parents of the 9.343 + dirstate as <emphasis>the parents of a new 9.344 + changeset</emphasis> when you perform a commit.</para> 9.345 + 9.346 + <figure id="fig:concepts:wdir"> 9.347 + <title>The working directory can have two parents</title> 9.348 + <mediaobject> 9.349 + <imageobject><imagedata fileref="figs/wdir.png"/></imageobject> 9.350 + <textobject><phrase>XXX add text</phrase></textobject> 9.351 + </mediaobject> 9.352 + </figure> 9.353 + 9.354 + <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the 9.355 + normal state of the working directory, where it has a single 9.356 + changeset as parent. That changeset is the 9.357 + <emphasis>tip</emphasis>, the newest changeset in the 9.358 + repository that has no children.</para> 9.359 + 9.360 + <figure id="fig:concepts:wdir-after-commit"> 9.361 + <title>The working directory gains new parents after a 9.362 + commit</title> 9.363 + <mediaobject> 9.364 + <imageobject><imagedata fileref="figs/wdir-after-commit.png"/></imageobject> 9.365 + <textobject><phrase>XXX add text</phrase></textobject> 9.366 + </mediaobject> 9.367 + </figure> 9.368 + 9.369 + <para id="x_30f">It's useful to think of the working directory as 9.370 + <quote>the changeset I'm about to commit</quote>. Any files 9.371 + that you tell Mercurial that you've added, removed, renamed, 9.372 + or copied will be reflected in that changeset, as will 9.373 + modifications to any files that Mercurial is already tracking; 9.374 + the new changeset will have the parents of the working 9.375 + directory as its parents.</para> 9.376 + 9.377 + <para id="x_310">After a commit, Mercurial will update the 9.378 + parents of the working directory, so that the first parent is 9.379 + the ID of the new changeset, and the second is the null ID. 9.380 + This is shown in <xref 9.381 + linkend="fig:concepts:wdir-after-commit"/>. Mercurial 9.382 + doesn't touch any of the files in the working directory when 9.383 + you commit; it just modifies the dirstate to note its new 9.384 + parents.</para> 9.385 + 9.386 + </sect2> 9.387 + <sect2> 9.388 + <title>Creating a new head</title> 9.389 + 9.390 + <para id="x_311">It's perfectly normal to update the working directory to a 9.391 + changeset other than the current tip. For example, you might 9.392 + want to know what your project looked like last Tuesday, or 9.393 + you could be looking through changesets to see which one 9.394 + introduced a bug. In cases like this, the natural thing to do 9.395 + is update the working directory to the changeset you're 9.396 + interested in, and then examine the files in the working 9.397 + directory directly to see their contents as they were when you 9.398 + committed that changeset. The effect of this is shown in 9.399 + <xref linkend="fig:concepts:wdir-pre-branch"/>.</para> 9.400 + 9.401 + <figure id="fig:concepts:wdir-pre-branch"> 9.402 + <title>The working directory, updated to an older 9.403 + changeset</title> 9.404 + <mediaobject> 9.405 + <imageobject><imagedata fileref="figs/wdir-pre-branch.png"/></imageobject> 9.406 + <textobject><phrase>XXX add text</phrase></textobject> 9.407 + </mediaobject> 9.408 + </figure> 9.409 + 9.410 + <para id="x_313">Having updated the working directory to an 9.411 + older changeset, what happens if you make some changes, and 9.412 + then commit? Mercurial behaves in the same way as I outlined 9.413 + above. The parents of the working directory become the 9.414 + parents of the new changeset. This new changeset has no 9.415 + children, so it becomes the new tip. And the repository now 9.416 + contains two changesets that have no children; we call these 9.417 + <emphasis>heads</emphasis>. You can see the structure that 9.418 + this creates in <xref 9.419 + linkend="fig:concepts:wdir-branch"/>.</para> 9.420 + 9.421 + <figure id="fig:concepts:wdir-branch"> 9.422 + <title>After a commit made while synced to an older 9.423 + changeset</title> 9.424 + <mediaobject> 9.425 + <imageobject><imagedata fileref="figs/wdir-branch.png"/></imageobject> 9.426 + <textobject><phrase>XXX add text</phrase></textobject> 9.427 + </mediaobject> 9.428 + </figure> 9.429 + 9.430 + <note> 9.431 + <para id="x_315">If you're new to Mercurial, you should keep 9.432 + in mind a common <quote>error</quote>, which is to use the 9.433 + <command role="hg-cmd">hg pull</command> command without any 9.434 + options. By default, the <command role="hg-cmd">hg 9.435 + pull</command> command <emphasis>does not</emphasis> 9.436 + update the working directory, so you'll bring new changesets 9.437 + into your repository, but the working directory will stay 9.438 + synced at the same changeset as before the pull. If you 9.439 + make some changes and commit afterwards, you'll thus create 9.440 + a new head, because your working directory isn't synced to 9.441 + whatever the current tip is. To combine the operation of a 9.442 + pull, followed by an update, run <command>hg pull 9.443 + -u</command>.</para> 9.444 + 9.445 + <para id="x_316">I put the word <quote>error</quote> in quotes 9.446 + because all that you need to do to rectify the situation 9.447 + where you created a new head by accident is 9.448 + <command role="hg-cmd">hg merge</command>, then <command 9.449 + role="hg-cmd">hg commit</command>. In other words, this 9.450 + almost never has negative consequences; it's just something 9.451 + of a surprise for newcomers. I'll discuss other ways to 9.452 + avoid this behavior, and why Mercurial behaves in this 9.453 + initially surprising way, later on.</para> 9.454 + </note> 9.455 + 9.456 + </sect2> 9.457 + <sect2> 9.458 + <title>Merging changes</title> 9.459 + 9.460 + <para id="x_317">When you run the <command role="hg-cmd">hg 9.461 + merge</command> command, Mercurial leaves the first parent 9.462 + of the working directory unchanged, and sets the second parent 9.463 + to the changeset you're merging with, as shown in <xref 9.464 + linkend="fig:concepts:wdir-merge"/>.</para> 9.465 + 9.466 + <figure id="fig:concepts:wdir-merge"> 9.467 + <title>Merging two heads</title> 9.468 + <mediaobject> 9.469 + <imageobject> 9.470 + <imagedata fileref="figs/wdir-merge.png"/> 9.471 + </imageobject> 9.472 + <textobject><phrase>XXX add text</phrase></textobject> 9.473 + </mediaobject> 9.474 + </figure> 9.475 + 9.476 + <para id="x_319">Mercurial also has to modify the working directory, to 9.477 + merge the files managed in the two changesets. Simplified a 9.478 + little, the merging process goes like this, for every file in 9.479 + the manifests of both changesets.</para> 9.480 + <itemizedlist> 9.481 + <listitem><para id="x_31a">If neither changeset has modified a file, do 9.482 + nothing with that file.</para> 9.483 + </listitem> 9.484 + <listitem><para id="x_31b">If one changeset has modified a file, and the 9.485 + other hasn't, create the modified copy of the file in the 9.486 + working directory.</para> 9.487 + </listitem> 9.488 + <listitem><para id="x_31c">If one changeset has removed a file, and the 9.489 + other hasn't (or has also deleted it), delete the file 9.490 + from the working directory.</para> 9.491 + </listitem> 9.492 + <listitem><para id="x_31d">If one changeset has removed a file, but the 9.493 + other has modified the file, ask the user what to do: keep 9.494 + the modified file, or remove it?</para> 9.495 + </listitem> 9.496 + <listitem><para id="x_31e">If both changesets have modified a file, 9.497 + invoke an external merge program to choose the new 9.498 + contents for the merged file. This may require input from 9.499 + the user.</para> 9.500 + </listitem> 9.501 + <listitem><para id="x_31f">If one changeset has modified a file, and the 9.502 + other has renamed or copied the file, make sure that the 9.503 + changes follow the new name of the file.</para> 9.504 + </listitem></itemizedlist> 9.505 + <para id="x_320">There are more details&emdash;merging has plenty of corner 9.506 + cases&emdash;but these are the most common choices that are 9.507 + involved in a merge. As you can see, most cases are 9.508 + completely automatic, and indeed most merges finish 9.509 + automatically, without requiring your input to resolve any 9.510 + conflicts.</para> 9.511 + 9.512 + <para id="x_321">When you're thinking about what happens when you commit 9.513 + after a merge, once again the working directory is <quote>the 9.514 + changeset I'm about to commit</quote>. After the <command 9.515 + role="hg-cmd">hg merge</command> command completes, the 9.516 + working directory has two parents; these will become the 9.517 + parents of the new changeset.</para> 9.518 + 9.519 + <para id="x_322">Mercurial lets you perform multiple merges, but 9.520 + you must commit the results of each individual merge as you 9.521 + go. This is necessary because Mercurial only tracks two 9.522 + parents for both revisions and the working directory. While 9.523 + it would be technically feasible to merge multiple changesets 9.524 + at once, Mercurial avoids this for simplicity. With multi-way 9.525 + merges, the risks of user confusion, nasty conflict 9.526 + resolution, and making a terrible mess of a merge would grow 9.527 + intolerable.</para> 9.528 + 9.529 + </sect2> 9.530 + 9.531 + <sect2> 9.532 + <title>Merging and renames</title> 9.533 + 9.534 + <para id="x_69a">A surprising number of revision control systems pay little 9.535 + or no attention to a file's <emphasis>name</emphasis> over 9.536 + time. For instance, it used to be common that if a file got 9.537 + renamed on one side of a merge, the changes from the other 9.538 + side would be silently dropped.</para> 9.539 + 9.540 + <para id="x_69b">Mercurial records metadata when you tell it to perform a 9.541 + rename or copy. It uses this metadata during a merge to do the 9.542 + right thing in the case of a merge. For instance, if I rename 9.543 + a file, and you edit it without renaming it, when we merge our 9.544 + work the file will be renamed and have your edits 9.545 + applied.</para> 9.546 + </sect2> 9.547 + </sect1> 9.548 + 9.549 + <sect1> 9.550 + <title>Other interesting design features</title> 9.551 + 9.552 + <para id="x_323">In the sections above, I've tried to highlight some of the 9.553 + most important aspects of Mercurial's design, to illustrate that 9.554 + it pays careful attention to reliability and performance. 9.555 + However, the attention to detail doesn't stop there. There are 9.556 + a number of other aspects of Mercurial's construction that I 9.557 + personally find interesting. I'll detail a few of them here, 9.558 + separate from the <quote>big ticket</quote> items above, so that 9.559 + if you're interested, you can gain a better idea of the amount 9.560 + of thinking that goes into a well-designed system.</para> 9.561 + 9.562 + <sect2> 9.563 + <title>Clever compression</title> 9.564 + 9.565 + <para id="x_324">When appropriate, Mercurial will store both snapshots and 9.566 + deltas in compressed form. It does this by always 9.567 + <emphasis>trying to</emphasis> compress a snapshot or delta, 9.568 + but only storing the compressed version if it's smaller than 9.569 + the uncompressed version.</para> 9.570 + 9.571 + <para id="x_325">This means that Mercurial does <quote>the right 9.572 + thing</quote> when storing a file whose native form is 9.573 + compressed, such as a <literal>zip</literal> archive or a JPEG 9.574 + image. When these types of files are compressed a second 9.575 + time, the resulting file is usually bigger than the 9.576 + once-compressed form, and so Mercurial will store the plain 9.577 + <literal>zip</literal> or JPEG.</para> 9.578 + 9.579 + <para id="x_326">Deltas between revisions of a compressed file are usually 9.580 + larger than snapshots of the file, and Mercurial again does 9.581 + <quote>the right thing</quote> in these cases. It finds that 9.582 + such a delta exceeds the threshold at which it should store a 9.583 + complete snapshot of the file, so it stores the snapshot, 9.584 + again saving space compared to a naive delta-only 9.585 + approach.</para> 9.586 + 9.587 + <sect3> 9.588 + <title>Network recompression</title> 9.589 + 9.590 + <para id="x_327">When storing revisions on disk, Mercurial uses the 9.591 + <quote>deflate</quote> compression algorithm (the same one 9.592 + used by the popular <literal>zip</literal> archive format), 9.593 + which balances good speed with a respectable compression 9.594 + ratio. However, when transmitting revision data over a 9.595 + network connection, Mercurial uncompresses the compressed 9.596 + revision data.</para> 9.597 + 9.598 + <para id="x_328">If the connection is over HTTP, Mercurial recompresses 9.599 + the entire stream of data using a compression algorithm that 9.600 + gives a better compression ratio (the Burrows-Wheeler 9.601 + algorithm from the widely used <literal>bzip2</literal> 9.602 + compression package). This combination of algorithm and 9.603 + compression of the entire stream (instead of a revision at a 9.604 + time) substantially reduces the number of bytes to be 9.605 + transferred, yielding better network performance over most 9.606 + kinds of network.</para> 9.607 + 9.608 + <para id="x_329">If the connection is over 9.609 + <command>ssh</command>, Mercurial 9.610 + <emphasis>doesn't</emphasis> recompress the stream, because 9.611 + <command>ssh</command> can already do this itself. You can 9.612 + tell Mercurial to always use <command>ssh</command>'s 9.613 + compression feature by editing the 9.614 + <filename>.hgrc</filename> file in your home directory as 9.615 + follows.</para> 9.616 + 9.617 + <programlisting>[ui] 9.618 +ssh = ssh -C</programlisting> 9.619 + 9.620 + </sect3> 9.621 + </sect2> 9.622 + <sect2> 9.623 + <title>Read/write ordering and atomicity</title> 9.624 + 9.625 + <para id="x_32a">Appending to files isn't the whole story when 9.626 + it comes to guaranteeing that a reader won't see a partial 9.627 + write. If you recall <xref linkend="fig:concepts:metadata"/>, 9.628 + revisions in the changelog point to revisions in the manifest, 9.629 + and revisions in the manifest point to revisions in filelogs. 9.630 + This hierarchy is deliberate.</para> 9.631 + 9.632 + <para id="x_32b">A writer starts a transaction by writing filelog and 9.633 + manifest data, and doesn't write any changelog data until 9.634 + those are finished. A reader starts by reading changelog 9.635 + data, then manifest data, followed by filelog data.</para> 9.636 + 9.637 + <para id="x_32c">Since the writer has always finished writing filelog and 9.638 + manifest data before it writes to the changelog, a reader will 9.639 + never read a pointer to a partially written manifest revision 9.640 + from the changelog, and it will never read a pointer to a 9.641 + partially written filelog revision from the manifest.</para> 9.642 + 9.643 + </sect2> 9.644 + <sect2> 9.645 + <title>Concurrent access</title> 9.646 + 9.647 + <para id="x_32d">The read/write ordering and atomicity guarantees mean that 9.648 + Mercurial never needs to <emphasis>lock</emphasis> a 9.649 + repository when it's reading data, even if the repository is 9.650 + being written to while the read is occurring. This has a big 9.651 + effect on scalability; you can have an arbitrary number of 9.652 + Mercurial processes safely reading data from a repository 9.653 + all at once, no matter whether it's being written to or 9.654 + not.</para> 9.655 + 9.656 + <para id="x_32e">The lockless nature of reading means that if you're 9.657 + sharing a repository on a multi-user system, you don't need to 9.658 + grant other local users permission to 9.659 + <emphasis>write</emphasis> to your repository in order for 9.660 + them to be able to clone it or pull changes from it; they only 9.661 + need <emphasis>read</emphasis> permission. (This is 9.662 + <emphasis>not</emphasis> a common feature among revision 9.663 + control systems, so don't take it for granted! Most require 9.664 + readers to be able to lock a repository to access it safely, 9.665 + and this requires write permission on at least one directory, 9.666 + which of course makes for all kinds of nasty and annoying 9.667 + security and administrative problems.)</para> 9.668 + 9.669 + <para id="x_32f">Mercurial uses locks to ensure that only one process can 9.670 + write to a repository at a time (the locking mechanism is safe 9.671 + even over filesystems that are notoriously hostile to locking, 9.672 + such as NFS). If a repository is locked, a writer will wait 9.673 + for a while to retry if the repository becomes unlocked, but 9.674 + if the repository remains locked for too long, the process 9.675 + attempting to write will time out after a while. This means 9.676 + that your daily automated scripts won't get stuck forever and 9.677 + pile up if a system crashes unnoticed, for example. (Yes, the 9.678 + timeout is configurable, from zero to infinity.)</para> 9.679 + 9.680 + <sect3> 9.681 + <title>Safe dirstate access</title> 9.682 + 9.683 + <para id="x_330">As with revision data, Mercurial doesn't take a lock to 9.684 + read the dirstate file; it does acquire a lock to write it. 9.685 + To avoid the possibility of reading a partially written copy 9.686 + of the dirstate file, Mercurial writes to a file with a 9.687 + unique name in the same directory as the dirstate file, then 9.688 + renames the temporary file atomically to 9.689 + <filename>dirstate</filename>. The file named 9.690 + <filename>dirstate</filename> is thus guaranteed to be 9.691 + complete, not partially written.</para> 9.692 + 9.693 + </sect3> 9.694 + </sect2> 9.695 + <sect2> 9.696 + <title>Avoiding seeks</title> 9.697 + 9.698 + <para id="x_331">Critical to Mercurial's performance is the avoidance of 9.699 + seeks of the disk head, since any seek is far more expensive 9.700 + than even a comparatively large read operation.</para> 9.701 + 9.702 + <para id="x_332">This is why, for example, the dirstate is stored in a 9.703 + single file. If there were a dirstate file per directory that 9.704 + Mercurial tracked, the disk would seek once per directory. 9.705 + Instead, Mercurial reads the entire single dirstate file in 9.706 + one step.</para> 9.707 + 9.708 + <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme 9.709 + when cloning a repository on local storage. Instead of 9.710 + copying every revlog file from the old repository into the new 9.711 + repository, it makes a <quote>hard link</quote>, which is a 9.712 + shorthand way to say <quote>these two names point to the same 9.713 + file</quote>. When Mercurial is about to write to one of a 9.714 + revlog's files, it checks to see if the number of names 9.715 + pointing at the file is greater than one. If it is, more than 9.716 + one repository is using the file, so Mercurial makes a new 9.717 + copy of the file that is private to this repository.</para> 9.718 + 9.719 + <para id="x_334">A few revision control developers have pointed out that 9.720 + this idea of making a complete private copy of a file is not 9.721 + very efficient in its use of storage. While this is true, 9.722 + storage is cheap, and this method gives the highest 9.723 + performance while deferring most book-keeping to the operating 9.724 + system. An alternative scheme would most likely reduce 9.725 + performance and increase the complexity of the software, but 9.726 + speed and simplicity are key to the <quote>feel</quote> of 9.727 + day-to-day use.</para> 9.728 + 9.729 + </sect2> 9.730 + <sect2> 9.731 + <title>Other contents of the dirstate</title> 9.732 + 9.733 + <para id="x_335">Because Mercurial doesn't force you to tell it when you're 9.734 + modifying a file, it uses the dirstate to store some extra 9.735 + information so it can determine efficiently whether you have 9.736 + modified a file. For each file in the working directory, it 9.737 + stores the time that it last modified the file itself, and the 9.738 + size of the file at that time.</para> 9.739 + 9.740 + <para id="x_336">When you explicitly <command role="hg-cmd">hg 9.741 + add</command>, <command role="hg-cmd">hg remove</command>, 9.742 + <command role="hg-cmd">hg rename</command> or <command 9.743 + role="hg-cmd">hg copy</command> files, Mercurial updates the 9.744 + dirstate so that it knows what to do with those files when you 9.745 + commit.</para> 9.746 + 9.747 + <para id="x_337">The dirstate helps Mercurial to efficiently 9.748 + check the status of files in a repository.</para> 9.749 + 9.750 + <itemizedlist> 9.751 + <listitem> 9.752 + <para id="x_726">When Mercurial checks the state of a file in the 9.753 + working directory, it first checks a file's modification 9.754 + time against the time in the dirstate that records when 9.755 + Mercurial last wrote the file. If the last modified time 9.756 + is the same as the time when Mercurial wrote the file, the 9.757 + file must not have been modified, so Mercurial does not 9.758 + need to check any further.</para> 9.759 + </listitem> 9.760 + <listitem> 9.761 + <para id="x_727">If the file's size has changed, the file must have 9.762 + been modified. If the modification time has changed, but 9.763 + the size has not, only then does Mercurial need to 9.764 + actually read the contents of the file to see if it has 9.765 + changed.</para> 9.766 + </listitem> 9.767 + </itemizedlist> 9.768 + 9.769 + <para id="x_728">Storing the modification time and size dramatically 9.770 + reduces the number of read operations that Mercurial needs to 9.771 + perform when we run commands like <command>hg status</command>. 9.772 + This results in large performance improvements.</para> 9.773 + </sect2> 9.774 + </sect1> 9.775 +</chapter> 9.776 + 9.777 +<!-- 9.778 +local variables: 9.779 +sgml-parent-document: ("00book.xml" "book" "chapter") 9.780 +end: 9.781 +-->
10.1 --- a/en/ch04-daily.xml Thu May 07 21:06:49 2009 -0700 10.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 10.3 @@ -1,840 +0,0 @@ 10.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 10.5 - 10.6 -<chapter id="chap:daily"> 10.7 - <?dbhtml filename="mercurial-in-daily-use.html"?> 10.8 - <title>Mercurial in daily use</title> 10.9 - 10.10 - <sect1> 10.11 - <title>Telling Mercurial which files to track</title> 10.12 - 10.13 - <para id="x_1a3">Mercurial does not work with files in your repository unless 10.14 - you tell it to manage them. The <command role="hg-cmd">hg 10.15 - status</command> command will tell you which files Mercurial 10.16 - doesn't know about; it uses a 10.17 - <quote><literal>?</literal></quote> to display such 10.18 - files.</para> 10.19 - 10.20 - <para id="x_1a4">To tell Mercurial to track a file, use the <command 10.21 - role="hg-cmd">hg add</command> command. Once you have added a 10.22 - file, the entry in the output of <command role="hg-cmd">hg 10.23 - status</command> for that file changes from 10.24 - <quote><literal>?</literal></quote> to 10.25 - <quote><literal>A</literal></quote>.</para> 10.26 - 10.27 - &interaction.daily.files.add; 10.28 - 10.29 - <para id="x_1a5">After you run a <command role="hg-cmd">hg commit</command>, 10.30 - the files that you added before the commit will no longer be 10.31 - listed in the output of <command role="hg-cmd">hg 10.32 - status</command>. The reason for this is that by default, <command 10.33 - role="hg-cmd">hg status</command> only tells you about 10.34 - <quote>interesting</quote> files&emdash;those that you have (for 10.35 - example) modified, removed, or renamed. If you have a repository 10.36 - that contains thousands of files, you will rarely want to know 10.37 - about files that Mercurial is tracking, but that have not 10.38 - changed. (You can still get this information; we'll return to 10.39 - this later.)</para> 10.40 - 10.41 - <para id="x_1a6">Once you add a file, Mercurial doesn't do anything with it 10.42 - immediately. Instead, it will take a snapshot of the file's 10.43 - state the next time you perform a commit. It will then continue 10.44 - to track the changes you make to the file every time you commit, 10.45 - until you remove the file.</para> 10.46 - 10.47 - <sect2> 10.48 - <title>Explicit versus implicit file naming</title> 10.49 - 10.50 - <para id="x_1a7">A useful behavior that Mercurial has is that if you pass 10.51 - the name of a directory to a command, every Mercurial command 10.52 - will treat this as <quote>I want to operate on every file in 10.53 - this directory and its subdirectories</quote>.</para> 10.54 - 10.55 - &interaction.daily.files.add-dir; 10.56 - 10.57 - <para id="x_1a8">Notice in this example that Mercurial printed 10.58 - the names of the files it added, whereas it didn't do so when 10.59 - we added the file named <filename>myfile.txt</filename> in the 10.60 - earlier example.</para> 10.61 - 10.62 - <para id="x_1a9">What's going on is that in the former case, we explicitly 10.63 - named the file to add on the command line. The assumption 10.64 - that Mercurial makes in such cases is that we know what we 10.65 - are doing, and it doesn't print any output.</para> 10.66 - 10.67 - <para id="x_1aa">However, when we <emphasis>imply</emphasis> the names of 10.68 - files by giving the name of a directory, Mercurial takes the 10.69 - extra step of printing the name of each file that it does 10.70 - something with. This makes it more clear what is happening, 10.71 - and reduces the likelihood of a silent and nasty surprise. 10.72 - This behavior is common to most Mercurial commands.</para> 10.73 - </sect2> 10.74 - 10.75 - <sect2> 10.76 - <title>Mercurial tracks files, not directories</title> 10.77 - 10.78 - <para id="x_1ab">Mercurial does not track directory information. Instead, 10.79 - it tracks the path to a file. Before creating a file, it 10.80 - first creates any missing directory components of the path. 10.81 - After it deletes a file, it then deletes any empty directories 10.82 - that were in the deleted file's path. This sounds like a 10.83 - trivial distinction, but it has one minor practical 10.84 - consequence: it is not possible to represent a completely 10.85 - empty directory in Mercurial.</para> 10.86 - 10.87 - <para id="x_1ac">Empty directories are rarely useful, and there are 10.88 - unintrusive workarounds that you can use to achieve an 10.89 - appropriate effect. The developers of Mercurial thus felt 10.90 - that the complexity that would be required to manage empty 10.91 - directories was not worth the limited benefit this feature 10.92 - would bring.</para> 10.93 - 10.94 - <para id="x_1ad">If you need an empty directory in your repository, there 10.95 - are a few ways to achieve this. One is to create a directory, 10.96 - then <command role="hg-cmd">hg add</command> a 10.97 - <quote>hidden</quote> file to that directory. On Unix-like 10.98 - systems, any file name that begins with a period 10.99 - (<quote><literal>.</literal></quote>) is treated as hidden by 10.100 - most commands and GUI tools. This approach is illustrated 10.101 - below.</para> 10.102 - 10.103 -&interaction.daily.files.hidden; 10.104 - 10.105 - <para id="x_1ae">Another way to tackle a need for an empty directory is to 10.106 - simply create one in your automated build scripts before they 10.107 - will need it.</para> 10.108 - </sect2> 10.109 - </sect1> 10.110 - 10.111 - <sect1> 10.112 - <title>How to stop tracking a file</title> 10.113 - 10.114 - <para id="x_1af">Once you decide that a file no longer belongs in 10.115 - your repository, use the <command role="hg-cmd">hg 10.116 - remove</command> command. This deletes the file, and tells 10.117 - Mercurial to stop tracking it (which will occur at the next 10.118 - commit). A removed file is represented in the output of 10.119 - <command role="hg-cmd">hg status</command> with a 10.120 - <quote><literal>R</literal></quote>.</para> 10.121 - 10.122 - &interaction.daily.files.remove; 10.123 - 10.124 - <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file, 10.125 - Mercurial will no longer track changes to that file, even if you 10.126 - recreate a file with the same name in your working directory. 10.127 - If you do recreate a file with the same name and want Mercurial 10.128 - to track the new file, simply <command role="hg-cmd">hg 10.129 - add</command> it. Mercurial will know that the newly added 10.130 - file is not related to the old file of the same name.</para> 10.131 - 10.132 - <sect2> 10.133 - <title>Removing a file does not affect its history</title> 10.134 - 10.135 - <para id="x_1b1">It is important to understand that removing a file has 10.136 - only two effects.</para> 10.137 - <itemizedlist> 10.138 - <listitem><para id="x_1b2">It removes the current version of the file 10.139 - from the working directory.</para> 10.140 - </listitem> 10.141 - <listitem><para id="x_1b3">It stops Mercurial from tracking changes to 10.142 - the file, from the time of the next commit.</para> 10.143 - </listitem></itemizedlist> 10.144 - <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way 10.145 - alter the <emphasis>history</emphasis> of the file.</para> 10.146 - 10.147 - <para id="x_1b5">If you update the working directory to a 10.148 - changeset that was committed when it was still tracking a file 10.149 - that you later removed, the file will reappear in the working 10.150 - directory, with the contents it had when you committed that 10.151 - changeset. If you then update the working directory to a 10.152 - later changeset, in which the file had been removed, Mercurial 10.153 - will once again remove the file from the working 10.154 - directory.</para> 10.155 - </sect2> 10.156 - 10.157 - <sect2> 10.158 - <title>Missing files</title> 10.159 - 10.160 - <para id="x_1b6">Mercurial considers a file that you have deleted, but not 10.161 - used <command role="hg-cmd">hg remove</command> to delete, to 10.162 - be <emphasis>missing</emphasis>. A missing file is 10.163 - represented with <quote><literal>!</literal></quote> in the 10.164 - output of <command role="hg-cmd">hg status</command>. 10.165 - Mercurial commands will not generally do anything with missing 10.166 - files.</para> 10.167 - 10.168 - &interaction.daily.files.missing; 10.169 - 10.170 - <para id="x_1b7">If your repository contains a file that <command 10.171 - role="hg-cmd">hg status</command> reports as missing, and 10.172 - you want the file to stay gone, you can run <command 10.173 - role="hg-cmd">hg remove <option 10.174 - role="hg-opt-remove">--after</option></command> at any 10.175 - time later on, to tell Mercurial that you really did mean to 10.176 - remove the file.</para> 10.177 - 10.178 - &interaction.daily.files.remove-after; 10.179 - 10.180 - <para id="x_1b8">On the other hand, if you deleted the missing file by 10.181 - accident, give <command role="hg-cmd">hg revert</command> the 10.182 - name of the file to recover. It will reappear, in unmodified 10.183 - form.</para> 10.184 - 10.185 - &interaction.daily.files.recover-missing; 10.186 - </sect2> 10.187 - 10.188 - <sect2> 10.189 - <title>Aside: why tell Mercurial explicitly to remove a 10.190 - file?</title> 10.191 - 10.192 - <para id="x_1b9">You might wonder why Mercurial requires you to explicitly 10.193 - tell it that you are deleting a file. Early during the 10.194 - development of Mercurial, it let you delete a file however you 10.195 - pleased; Mercurial would notice the absence of the file 10.196 - automatically when you next ran a <command role="hg-cmd">hg 10.197 - commit</command>, and stop tracking the file. In practice, 10.198 - this made it too easy to accidentally remove a file without 10.199 - noticing.</para> 10.200 - </sect2> 10.201 - 10.202 - <sect2> 10.203 - <title>Useful shorthand&emdash;adding and removing files in one 10.204 - step</title> 10.205 - 10.206 - <para id="x_1ba">Mercurial offers a combination command, <command 10.207 - role="hg-cmd">hg addremove</command>, that adds untracked 10.208 - files and marks missing files as removed.</para> 10.209 - 10.210 - &interaction.daily.files.addremove; 10.211 - 10.212 - <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command 10.213 - also provides a <option role="hg-opt-commit">-A</option> 10.214 - option that performs this same add-and-remove, immediately 10.215 - followed by a commit.</para> 10.216 - 10.217 - &interaction.daily.files.commit-addremove; 10.218 - </sect2> 10.219 - </sect1> 10.220 - 10.221 - <sect1 id="chap:daily.copy"> 10.222 - <title>Copying files</title> 10.223 - 10.224 - <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg 10.225 - copy</command> command that lets you make a new copy of a 10.226 - file. When you copy a file using this command, Mercurial makes 10.227 - a record of the fact that the new file is a copy of the original 10.228 - file. It treats these copied files specially when you merge 10.229 - your work with someone else's.</para> 10.230 - 10.231 - <sect2> 10.232 - <title>The results of copying during a merge</title> 10.233 - 10.234 - <para id="x_1bd">What happens during a merge is that changes 10.235 - <quote>follow</quote> a copy. To best illustrate what this 10.236 - means, let's create an example. We'll start with the usual 10.237 - tiny repository that contains a single file.</para> 10.238 - 10.239 - &interaction.daily.copy.init; 10.240 - 10.241 - <para id="x_1be">We need to do some work in 10.242 - parallel, so that we'll have something to merge. So let's 10.243 - clone our repository.</para> 10.244 - 10.245 - &interaction.daily.copy.clone; 10.246 - 10.247 - <para id="x_1bf">Back in our initial repository, let's use the <command 10.248 - role="hg-cmd">hg copy</command> command to make a copy of 10.249 - the first file we created.</para> 10.250 - 10.251 - &interaction.daily.copy.copy; 10.252 - 10.253 - <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg 10.254 - status</command> command afterwards, the copied file looks 10.255 - just like a normal added file.</para> 10.256 - 10.257 - &interaction.daily.copy.status; 10.258 - 10.259 - <para id="x_1c1">But if we pass the <option 10.260 - role="hg-opt-status">-C</option> option to <command 10.261 - role="hg-cmd">hg status</command>, it prints another line of 10.262 - output: this is the file that our newly-added file was copied 10.263 - <emphasis>from</emphasis>.</para> 10.264 - 10.265 - &interaction.daily.copy.status-copy; 10.266 - 10.267 - <para id="x_1c2">Now, back in the repository we cloned, let's make a change 10.268 - in parallel. We'll add a line of content to the original file 10.269 - that we created.</para> 10.270 - 10.271 - &interaction.daily.copy.other; 10.272 - 10.273 - <para id="x_1c3">Now we have a modified <filename>file</filename> in this 10.274 - repository. When we pull the changes from the first 10.275 - repository, and merge the two heads, Mercurial will propagate 10.276 - the changes that we made locally to <filename>file</filename> 10.277 - into its copy, <filename>new-file</filename>.</para> 10.278 - 10.279 - &interaction.daily.copy.merge; 10.280 - </sect2> 10.281 - 10.282 - <sect2 id="sec:daily:why-copy"> 10.283 - <title>Why should changes follow copies?</title> 10.284 - 10.285 - <para id="x_1c4">This behavior&emdash;of changes to a file 10.286 - propagating out to copies of the file&emdash;might seem 10.287 - esoteric, but in most cases it's highly desirable.</para> 10.288 - 10.289 - <para id="x_1c5">First of all, remember that this propagation 10.290 - <emphasis>only</emphasis> happens when you merge. So if you 10.291 - <command role="hg-cmd">hg copy</command> a file, and 10.292 - subsequently modify the original file during the normal course 10.293 - of your work, nothing will happen.</para> 10.294 - 10.295 - <para id="x_1c6">The second thing to know is that modifications will only 10.296 - propagate across a copy as long as the changeset that you're 10.297 - merging changes from <emphasis>hasn't yet seen</emphasis> 10.298 - the copy.</para> 10.299 - 10.300 - <para id="x_1c7">The reason that Mercurial does this is as follows. Let's 10.301 - say I make an important bug fix in a source file, and commit 10.302 - my changes. Meanwhile, you've decided to <command 10.303 - role="hg-cmd">hg copy</command> the file in your repository, 10.304 - without knowing about the bug or having seen the fix, and you 10.305 - have started hacking on your copy of the file.</para> 10.306 - 10.307 - <para id="x_1c8">If you pulled and merged my changes, and Mercurial 10.308 - <emphasis>didn't</emphasis> propagate changes across copies, 10.309 - your new source file would now contain the bug, and unless you 10.310 - knew to propagate the bug fix by hand, the bug would 10.311 - <emphasis>remain</emphasis> in your copy of the file.</para> 10.312 - 10.313 - <para id="x_1c9">By automatically propagating the change that fixed the bug 10.314 - from the original file to the copy, Mercurial prevents this 10.315 - class of problem. To my knowledge, Mercurial is the 10.316 - <emphasis>only</emphasis> revision control system that 10.317 - propagates changes across copies like this.</para> 10.318 - 10.319 - <para id="x_1ca">Once your change history has a record that the copy and 10.320 - subsequent merge occurred, there's usually no further need to 10.321 - propagate changes from the original file to the copied file, 10.322 - and that's why Mercurial only propagates changes across copies 10.323 - at the first merge, and not afterwards.</para> 10.324 - </sect2> 10.325 - 10.326 - <sect2> 10.327 - <title>How to make changes <emphasis>not</emphasis> follow a 10.328 - copy</title> 10.329 - 10.330 - <para id="x_1cb">If, for some reason, you decide that this business of 10.331 - automatically propagating changes across copies is not for 10.332 - you, simply use your system's normal file copy command (on 10.333 - Unix-like systems, that's <command>cp</command>) to make a 10.334 - copy of a file, then <command role="hg-cmd">hg add</command> 10.335 - the new copy by hand. Before you do so, though, please do 10.336 - reread <xref linkend="sec:daily:why-copy"/>, and make 10.337 - an informed 10.338 - decision that this behavior is not appropriate to your 10.339 - specific case.</para> 10.340 - 10.341 - </sect2> 10.342 - <sect2> 10.343 - <title>Behavior of the <command role="hg-cmd">hg copy</command> 10.344 - command</title> 10.345 - 10.346 - <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command> 10.347 - command, Mercurial makes a copy of each source file as it 10.348 - currently stands in the working directory. This means that if 10.349 - you make some modifications to a file, then <command 10.350 - role="hg-cmd">hg copy</command> it without first having 10.351 - committed those changes, the new copy will also contain the 10.352 - modifications you have made up until that point. (I find this 10.353 - behavior a little counterintuitive, which is why I mention it 10.354 - here.)</para> 10.355 - 10.356 - <para id="x_1cd">The <command role="hg-cmd">hg copy</command> 10.357 - command acts similarly to the Unix <command>cp</command> 10.358 - command (you can use the <command role="hg-cmd">hg 10.359 - cp</command> alias if you prefer). We must supply two or 10.360 - more arguments, of which the last is treated as the 10.361 - <emphasis>destination</emphasis>, and all others are 10.362 - <emphasis>sources</emphasis>.</para> 10.363 - 10.364 - <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a 10.365 - single file as the source, and the destination does not exist, 10.366 - it creates a new file with that name.</para> 10.367 - 10.368 - &interaction.daily.copy.simple; 10.369 - 10.370 - <para id="x_1ce">If the destination is a directory, Mercurial copies its 10.371 - sources into that directory.</para> 10.372 - 10.373 - &interaction.daily.copy.dir-dest; 10.374 - 10.375 - <para id="x_1cf">Copying a directory is 10.376 - recursive, and preserves the directory structure of the 10.377 - source.</para> 10.378 - 10.379 - &interaction.daily.copy.dir-src; 10.380 - 10.381 - <para id="x_1d0">If the source and destination are both directories, the 10.382 - source tree is recreated in the destination directory.</para> 10.383 - 10.384 - &interaction.daily.copy.dir-src-dest; 10.385 - 10.386 - <para id="x_1d1">As with the <command role="hg-cmd">hg remove</command> 10.387 - command, if you copy a file manually and then want Mercurial 10.388 - to know that you've copied the file, simply use the <option 10.389 - role="hg-opt-copy">--after</option> option to <command 10.390 - role="hg-cmd">hg copy</command>.</para> 10.391 - 10.392 - &interaction.daily.copy.after; 10.393 - </sect2> 10.394 - </sect1> 10.395 - 10.396 - <sect1> 10.397 - <title>Renaming files</title> 10.398 - 10.399 - <para id="x_1d2">It's rather more common to need to rename a file than to 10.400 - make a copy of it. The reason I discussed the <command 10.401 - role="hg-cmd">hg copy</command> command before talking about 10.402 - renaming files is that Mercurial treats a rename in essentially 10.403 - the same way as a copy. Therefore, knowing what Mercurial does 10.404 - when you copy a file tells you what to expect when you rename a 10.405 - file.</para> 10.406 - 10.407 - <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command> 10.408 - command, Mercurial makes a copy of each source file, then 10.409 - deletes it and marks the file as removed.</para> 10.410 - 10.411 - &interaction.daily.rename.rename; 10.412 - 10.413 - <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows 10.414 - the newly copied file as added, and the copied-from file as 10.415 - removed.</para> 10.416 - 10.417 - &interaction.daily.rename.status; 10.418 - 10.419 - <para id="x_1d5">As with the results of a <command role="hg-cmd">hg 10.420 - copy</command>, we must use the <option 10.421 - role="hg-opt-status">-C</option> option to <command 10.422 - role="hg-cmd">hg status</command> to see that the added file 10.423 - is really being tracked by Mercurial as a copy of the original, 10.424 - now removed, file.</para> 10.425 - 10.426 - &interaction.daily.rename.status-copy; 10.427 - 10.428 - <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and 10.429 - <command role="hg-cmd">hg copy</command>, you can tell Mercurial 10.430 - about a rename after the fact using the <option 10.431 - role="hg-opt-rename">--after</option> option. In most other 10.432 - respects, the behavior of the <command role="hg-cmd">hg 10.433 - rename</command> command, and the options it accepts, are 10.434 - similar to the <command role="hg-cmd">hg copy</command> 10.435 - command.</para> 10.436 - 10.437 - <para id="x_686">If you're familiar with the Unix command line, you'll be 10.438 - glad to know that <command role="hg-cmd">hg rename</command> 10.439 - command can be invoked as <command role="hg-cmd">hg 10.440 - mv</command>.</para> 10.441 - 10.442 - <sect2> 10.443 - <title>Renaming files and merging changes</title> 10.444 - 10.445 - <para id="x_1d7">Since Mercurial's rename is implemented as 10.446 - copy-and-remove, the same propagation of changes happens when 10.447 - you merge after a rename as after a copy.</para> 10.448 - 10.449 - <para id="x_1d8">If I modify a file, and you rename it to a new name, and 10.450 - then we merge our respective changes, my modifications to the 10.451 - file under its original name will be propagated into the file 10.452 - under its new name. (This is something you might expect to 10.453 - <quote>simply work,</quote> but not all revision control 10.454 - systems actually do this.)</para> 10.455 - 10.456 - <para id="x_1d9">Whereas having changes follow a copy is a feature where 10.457 - you can perhaps nod and say <quote>yes, that might be 10.458 - useful,</quote> it should be clear that having them follow a 10.459 - rename is definitely important. Without this facility, it 10.460 - would simply be too easy for changes to become orphaned when 10.461 - files are renamed.</para> 10.462 - </sect2> 10.463 - 10.464 - <sect2> 10.465 - <title>Divergent renames and merging</title> 10.466 - 10.467 - <para id="x_1da">The case of diverging names occurs when two developers 10.468 - start with a file&emdash;let's call it 10.469 - <filename>foo</filename>&emdash;in their respective 10.470 - repositories.</para> 10.471 - 10.472 - &interaction.rename.divergent.clone; 10.473 - 10.474 - <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para> 10.475 - 10.476 - &interaction.rename.divergent.rename.anne; 10.477 - 10.478 - <para id="x_1dc">Meanwhile, Bob renames it to 10.479 - <filename>quux</filename>. (Remember that <command 10.480 - role="hg-cmd">hg mv</command> is an alias for <command 10.481 - role="hg-cmd">hg rename</command>.)</para> 10.482 - 10.483 - &interaction.rename.divergent.rename.bob; 10.484 - 10.485 - <para id="x_1dd">I like to think of this as a conflict because each 10.486 - developer has expressed different intentions about what the 10.487 - file ought to be named.</para> 10.488 - 10.489 - <para id="x_1de">What do you think should happen when they merge their 10.490 - work? Mercurial's actual behavior is that it always preserves 10.491 - <emphasis>both</emphasis> names when it merges changesets that 10.492 - contain divergent renames.</para> 10.493 - 10.494 - &interaction.rename.divergent.merge; 10.495 - 10.496 - <para id="x_1df">Notice that while Mercurial warns about the divergent 10.497 - renames, it leaves it up to you to do something about the 10.498 - divergence after the merge.</para> 10.499 - </sect2> 10.500 - 10.501 - <sect2> 10.502 - <title>Convergent renames and merging</title> 10.503 - 10.504 - <para id="x_1e0">Another kind of rename conflict occurs when two people 10.505 - choose to rename different <emphasis>source</emphasis> files 10.506 - to the same <emphasis>destination</emphasis>. In this case, 10.507 - Mercurial runs its normal merge machinery, and lets you guide 10.508 - it to a suitable resolution.</para> 10.509 - </sect2> 10.510 - 10.511 - <sect2> 10.512 - <title>Other name-related corner cases</title> 10.513 - 10.514 - <para id="x_1e1">Mercurial has a longstanding bug in which it fails to 10.515 - handle a merge where one side has a file with a given name, 10.516 - while another has a directory with the same name. This is 10.517 - documented as <ulink role="hg-bug" 10.518 - url="http://www.selenic.com/mercurial/bts/issue29">issue 10.519 - 29</ulink>.</para> 10.520 - 10.521 - &interaction.issue29.go; 10.522 - 10.523 - </sect2> 10.524 - </sect1> 10.525 - 10.526 - <sect1> 10.527 - <title>Recovering from mistakes</title> 10.528 - 10.529 - <para id="x_1e2">Mercurial has some useful commands that will help you to 10.530 - recover from some common mistakes.</para> 10.531 - 10.532 - <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets 10.533 - you undo changes that you have made to your working directory. 10.534 - For example, if you <command role="hg-cmd">hg add</command> a 10.535 - file by accident, just run <command role="hg-cmd">hg 10.536 - revert</command> with the name of the file you added, and 10.537 - while the file won't be touched in any way, it won't be tracked 10.538 - for adding by Mercurial any longer, either. You can also use 10.539 - <command role="hg-cmd">hg revert</command> to get rid of 10.540 - erroneous changes to a file.</para> 10.541 - 10.542 - <para id="x_1e4">It is helpful to remember that the <command 10.543 - role="hg-cmd">hg revert</command> command is useful for 10.544 - changes that you have not yet committed. Once you've committed 10.545 - a change, if you decide it was a mistake, you can still do 10.546 - something about it, though your options may be more 10.547 - limited.</para> 10.548 - 10.549 - <para id="x_1e5">For more information about the <command 10.550 - role="hg-cmd">hg revert</command> command, and details about 10.551 - how to deal with changes you have already committed, see <xref 10.552 - linkend="chap:undo"/>.</para> 10.553 - </sect1> 10.554 - 10.555 - <sect1> 10.556 - <title>Dealing with tricky merges</title> 10.557 - 10.558 - <para id="x_687">In a complicated or large project, it's not unusual for a 10.559 - merge of two changesets to result in some headaches. Suppose 10.560 - there's a big source file that's been extensively edited by each 10.561 - side of a merge: this is almost inevitably going to result in 10.562 - conflicts, some of which can take a few tries to sort 10.563 - out.</para> 10.564 - 10.565 - <para id="x_688">Let's develop a simple case of this and see how to deal with 10.566 - it. We'll start off with a repository containing one file, and 10.567 - clone it twice.</para> 10.568 - 10.569 - &interaction.ch04-resolve.init; 10.570 - 10.571 - <para id="x_689">In one clone, we'll modify the file in one way.</para> 10.572 - 10.573 - &interaction.ch04-resolve.left; 10.574 - 10.575 - <para id="x_68a">In another, we'll modify the file differently.</para> 10.576 - 10.577 - &interaction.ch04-resolve.right; 10.578 - 10.579 - <para id="x_68b">Next, we'll pull each set of changes into our original 10.580 - repo.</para> 10.581 - 10.582 - &interaction.ch04-resolve.pull; 10.583 - 10.584 - <para id="x_68c">We expect our repository to now contain two heads.</para> 10.585 - 10.586 - &interaction.ch04-resolve.heads; 10.587 - 10.588 - <para id="x_68d">Normally, if we run <command role="hg-cmd">hg 10.589 - merge</command> at this point, it will drop us into a GUI that 10.590 - will let us manually resolve the conflicting edits to 10.591 - <filename>myfile.txt</filename>. However, to simplify things 10.592 - for presentation here, we'd like the merge to fail immediately 10.593 - instead. Here's one way we can do so.</para> 10.594 - 10.595 - &interaction.ch04-resolve.export; 10.596 - 10.597 - <para id="x_68e">We've told Mercurial's merge machinery to run the command 10.598 - <command>false</command> (which, as we desire, fails 10.599 - immediately) if it detects a merge that it can't sort out 10.600 - automatically.</para> 10.601 - 10.602 - <para id="x_68f">If we now fire up <command role="hg-cmd">hg 10.603 - merge</command>, it should grind to a halt and report a 10.604 - failure.</para> 10.605 - 10.606 - &interaction.ch04-resolve.merge; 10.607 - 10.608 - <para id="x_690">Even if we don't notice that the merge failed, Mercurial 10.609 - will prevent us from accidentally committing the result of a 10.610 - failed merge.</para> 10.611 - 10.612 - &interaction.ch04-resolve.cifail; 10.613 - 10.614 - <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in 10.615 - this case, it suggests that we use the unfamiliar <command 10.616 - role="hg-cmd">hg resolve</command> command. As usual, 10.617 - <command role="hg-cmd">hg help resolve</command> will print a 10.618 - helpful synopsis.</para> 10.619 - 10.620 - <sect2> 10.621 - <title>File resolution states</title> 10.622 - 10.623 - <para id="x_692">When a merge occurs, most files will usually remain 10.624 - unmodified. For each file where Mercurial has to do 10.625 - something, it tracks the state of the file.</para> 10.626 - 10.627 - <itemizedlist> 10.628 - <listitem> 10.629 - <para id="x_693">A <emphasis>resolved</emphasis> file has been 10.630 - successfully merged, either automatically by Mercurial or 10.631 - manually with human intervention.</para> 10.632 - </listitem> 10.633 - <listitem> 10.634 - <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged 10.635 - successfully, and needs more attention.</para> 10.636 - </listitem> 10.637 - </itemizedlist> 10.638 - 10.639 - <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the 10.640 - unresolved state after a merge, it considers the merge to have 10.641 - failed. Fortunately, we do not need to restart the entire 10.642 - merge from scratch.</para> 10.643 - 10.644 - <para id="x_696">The <option role="hg-opt-resolve">--list</option> or 10.645 - <option role="hg-opt-resolve">-l</option> option to <command 10.646 - role="hg-cmd">hg resolve</command> prints out the state of 10.647 - each merged file.</para> 10.648 - 10.649 - &interaction.ch04-resolve.list; 10.650 - 10.651 - <para id="x_697">In the output from <command role="hg-cmd">hg 10.652 - resolve</command>, a resolved file is marked with 10.653 - <literal>R</literal>, while an unresolved file is marked with 10.654 - <literal>U</literal>. If any files are listed with 10.655 - <literal>U</literal>, we know that an attempt to commit the 10.656 - results of the merge will fail.</para> 10.657 - </sect2> 10.658 - 10.659 - <sect2> 10.660 - <title>Resolving a file merge</title> 10.661 - 10.662 - <para id="x_698">We have several options to move a file from the unresolved 10.663 - into the resolved state. By far the most common is to rerun 10.664 - <command role="hg-cmd">hg resolve</command>. If we pass the 10.665 - names of individual files or directories, it will retry the 10.666 - merges of any unresolved files present in those locations. We 10.667 - can also pass the <option role="hg-opt-resolve">--all</option> 10.668 - or <option role="hg-opt-resolve">-a</option> option, which 10.669 - will retry the merges of <emphasis>all</emphasis> unresolved 10.670 - files.</para> 10.671 - 10.672 - <para id="x_699">Mercurial also lets us modify the resolution state of a 10.673 - file directly. We can manually mark a file as resolved using 10.674 - the <option role="hg-opt-resolve">--mark</option> option, or 10.675 - as unresolved using the <option 10.676 - role="hg-opt-resolve">--unmark</option> option. This allows 10.677 - us to clean up a particularly messy merge by hand, and to keep 10.678 - track of our progress with each file as we go.</para> 10.679 - </sect2> 10.680 - </sect1> 10.681 - 10.682 - <sect1> 10.683 - <title>More useful diffs</title> 10.684 - 10.685 - <para id="x_6c7">The default output of the <command role="hg-cmd">hg 10.686 - diff</command> command is backwards compatible with the 10.687 - regular <command>diff</command> command, but this has some 10.688 - drawbacks.</para> 10.689 - 10.690 - <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg 10.691 - rename</command> to rename a file.</para> 10.692 - 10.693 - &interaction.ch04-diff.rename.basic; 10.694 - 10.695 - <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above 10.696 - obscures the fact that we simply renamed a file. The <command 10.697 - role="hg-cmd">hg diff</command> command accepts an option, 10.698 - <option>--git</option> or <option>-g</option>, to use a newer 10.699 - diff format that displays such information in a more readable 10.700 - form.</para> 10.701 - 10.702 - &interaction.ch04-diff.rename.git; 10.703 - 10.704 - <para id="x_6ca">This option also helps with a case that can otherwise be 10.705 - confusing: a file that appears to be modified according to 10.706 - <command role="hg-cmd">hg status</command>, but for which 10.707 - <command role="hg-cmd">hg diff</command> prints nothing. This 10.708 - situation can arise if we change the file's execute 10.709 - permissions.</para> 10.710 - 10.711 - &interaction.ch04-diff.chmod; 10.712 - 10.713 - <para id="x_6cb">The normal <command>diff</command> command pays no attention 10.714 - to file permissions, which is why <command role="hg-cmd">hg 10.715 - diff</command> prints nothing by default. If we supply it 10.716 - with the <option>-g</option> option, it tells us what really 10.717 - happened.</para> 10.718 - 10.719 - &interaction.ch04-diff.chmod.git; 10.720 - </sect1> 10.721 - 10.722 - <sect1> 10.723 - <title>Which files to manage, and which to avoid</title> 10.724 - 10.725 - <para id="x_6cc">Revision control systems are generally best at managing text 10.726 - files that are written by humans, such as source code, where the 10.727 - files do not change much from one revision to the next. Some 10.728 - centralized revision control systems can also deal tolerably 10.729 - well with binary files, such as bitmap images.</para> 10.730 - 10.731 - <para id="x_6cd">For instance, a game development team will typically manage 10.732 - both its source code and all of its binary assets (e.g. geometry 10.733 - data, textures, map layouts) in a revision control 10.734 - system.</para> 10.735 - 10.736 - <para id="x_6ce">Because it is usually impossible to merge two conflicting 10.737 - modifications to a binary file, centralized systems often 10.738 - provide a file locking mechanism that allow a user to say 10.739 - <quote>I am the only person who can edit this 10.740 - file</quote>.</para> 10.741 - 10.742 - <para id="x_6cf">Compared to a centralized system, a distributed revision 10.743 - control system changes some of the factors that guide decisions 10.744 - over which files to manage and how.</para> 10.745 - 10.746 - <para id="x_6d0">For instance, a distributed revision control system cannot, 10.747 - by its nature, offer a file locking facility. There is thus no 10.748 - built-in mechanism to prevent two people from making conflicting 10.749 - changes to a binary file. If you have a team where several 10.750 - people may be editing binary files frequently, it may not be a 10.751 - good idea to use Mercurial&emdash;or any other distributed 10.752 - revision control system&emdash;to manage those files.</para> 10.753 - 10.754 - <para id="x_6d1">When storing modifications to a file, Mercurial usually 10.755 - saves only the differences between the previous and current 10.756 - versions of the file. For most text files, this is extremely 10.757 - efficient. However, some files (particularly binary files) are 10.758 - laid out in such a way that even a small change to a file's 10.759 - logical content results in many or most of the bytes inside the 10.760 - file changing. For instance, compressed files are particularly 10.761 - susceptible to this. If the differences between each successive 10.762 - version of a file are always large, Mercurial will not be able 10.763 - to store the file's revision history very efficiently. This can 10.764 - affect both local storage needs and the amount of time it takes 10.765 - to clone a repository.</para> 10.766 - 10.767 - <para id="x_6d2">To get an idea of how this could affect you in practice, 10.768 - suppose you want to use Mercurial to manage an OpenOffice 10.769 - document. OpenOffice stores documents on disk as compressed zip 10.770 - files. Edit even a single letter of your document in OpenOffice, 10.771 - and almost every byte in the entire file will change when you 10.772 - save it. Now suppose that file is 2MB in size. Because most of 10.773 - the file changes every time you save, Mercurial will have to 10.774 - store all 2MB of the file every time you commit, even though 10.775 - from your perspective, perhaps only a few words are changing 10.776 - each time. A single frequently-edited file that is not friendly 10.777 - to Mercurial's storage assumptions can easily have an outsized 10.778 - effect on the size of the repository.</para> 10.779 - 10.780 - <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice 10.781 - document you're working on, there is no useful way to merge your 10.782 - work. In fact, there isn't even a good way to tell what the 10.783 - differences are between your respective changes.</para> 10.784 - 10.785 - <para id="x_6d4">There are thus a few clear recommendations about specific 10.786 - kinds of files to be very careful with.</para> 10.787 - 10.788 - <itemizedlist> 10.789 - <listitem> 10.790 - <para id="x_6d5">Files that are very large and incompressible, e.g. ISO 10.791 - CD-ROM images, will by virtue of sheer size make clones over 10.792 - a network very slow.</para> 10.793 - </listitem> 10.794 - <listitem> 10.795 - <para id="x_6d6">Files that change a lot from one revision to the next 10.796 - may be expensive to store if you edit them frequently, and 10.797 - conflicts due to concurrent edits may be difficult to 10.798 - resolve.</para> 10.799 - </listitem> 10.800 - </itemizedlist> 10.801 - </sect1> 10.802 - 10.803 - <sect1> 10.804 - <title>Backups and mirroring</title> 10.805 - 10.806 - <para id="x_6d7">Since Mercurial maintains a complete copy of history in each 10.807 - clone, everyone who uses Mercurial to collaborate on a project 10.808 - can potentially act as a source of backups in the event of a 10.809 - catastrophe. If a central repository becomes unavailable, you 10.810 - can construct a replacement simply by cloning a copy of the 10.811 - repository from one contributor, and pulling any changes they 10.812 - may not have seen from others.</para> 10.813 - 10.814 - <para id="x_6d8">It is simple to use Mercurial to perform off-site backups 10.815 - and remote mirrors. Set up a periodic job (e.g. via the 10.816 - <command>cron</command> command) on a remote server to pull 10.817 - changes from your master repositories every hour. This will 10.818 - only be tricky in the unlikely case that the number of master 10.819 - repositories you maintain changes frequently, in which case 10.820 - you'll need to do a little scripting to refresh the list of 10.821 - repositories to back up.</para> 10.822 - 10.823 - <para id="x_6d9">If you perform traditional backups of your master 10.824 - repositories to tape or disk, and you want to back up a 10.825 - repository named <filename>myrepo</filename>, use <command>hg 10.826 - clone -U myrepo myrepo.bak</command> to create a 10.827 - clone of <filename>myrepo</filename> before you start your 10.828 - backups. The <option>-U</option> option doesn't check out a 10.829 - working directory after the clone completes, since that would be 10.830 - superfluous and make the backup take longer.</para> 10.831 - 10.832 - <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead 10.833 - of <filename>myrepo</filename>, you will be guaranteed to have a 10.834 - consistent snapshot of your repository that won't be pushed to 10.835 - by an insomniac developer in mid-backup.</para> 10.836 - </sect1> 10.837 -</chapter> 10.838 - 10.839 -<!-- 10.840 -local variables: 10.841 -sgml-parent-document: ("00book.xml" "book" "chapter") 10.842 -end: 10.843 --->
11.1 --- a/en/ch05-collab.xml Thu May 07 21:06:49 2009 -0700 11.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 11.3 @@ -1,1565 +0,0 @@ 11.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 11.5 - 11.6 -<chapter id="cha:collab"> 11.7 - <?dbhtml filename="collaborating-with-other-people.html"?> 11.8 - <title>Collaborating with other people</title> 11.9 - 11.10 - <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose 11.11 - any policy on how people ought to work with each other. However, 11.12 - if you're new to distributed revision control, it helps to have 11.13 - some tools and examples in mind when you're thinking about 11.14 - possible workflow models.</para> 11.15 - 11.16 - <sect1> 11.17 - <title>Mercurial's web interface</title> 11.18 - 11.19 - <para id="x_44b">Mercurial has a powerful web interface that provides several 11.20 - useful capabilities.</para> 11.21 - 11.22 - <para id="x_44c">For interactive use, the web interface lets you browse a 11.23 - single repository or a collection of repositories. You can view 11.24 - the history of a repository, examine each change (comments and 11.25 - diffs), and view the contents of each directory and file. You 11.26 - can even get a view of history that gives a graphical view of 11.27 - the relationships between individual changes and merges.</para> 11.28 - 11.29 - <para id="x_44d">Also for human consumption, the web interface provides 11.30 - Atom and RSS feeds of the changes in a repository. This lets you 11.31 - <quote>subscribe</quote> to a repository using your favorite 11.32 - feed reader, and be automatically notified of activity in that 11.33 - repository as soon as it happens. I find this capability much 11.34 - more convenient than the model of subscribing to a mailing list 11.35 - to which notifications are sent, as it requires no additional 11.36 - configuration on the part of whoever is serving the 11.37 - repository.</para> 11.38 - 11.39 - <para id="x_44e">The web interface also lets remote users clone a repository, 11.40 - pull changes from it, and (when the server is configured to 11.41 - permit it) push changes back to it. Mercurial's HTTP tunneling 11.42 - protocol aggressively compresses data, so that it works 11.43 - efficiently even over low-bandwidth network connections.</para> 11.44 - 11.45 - <para id="x_44f">The easiest way to get started with the web interface is to 11.46 - use your web browser to visit an existing repository, such as 11.47 - the master Mercurial repository at <ulink 11.48 - url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para> 11.49 - 11.50 - <para id="x_450">If you're interested in providing a web interface 11.51 - to your own repositories, there are several good ways to do 11.52 - this.</para> 11.53 - 11.54 - <para id="x_69d">The easiest and fastest way to get started in an informal 11.55 - environment is to use the <command role="hg-cmd">hg 11.56 - serve</command> command, which is best suited to short-term 11.57 - <quote>lightweight</quote> serving. See <xref 11.58 - linkend="sec:collab:serve"/> below for details of how to use 11.59 - this command.</para> 11.60 - 11.61 - <para id="x_69e">For longer-lived repositories that you'd like to 11.62 - have permanently available, there are several public hosting 11.63 - services available. Some are free to open source projects, 11.64 - while others offer paid commercial hosting. An up-to-date list 11.65 - is available at <ulink 11.66 - url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para> 11.67 - 11.68 - <para id="x_6a0">If you would prefer to host your own repositories, Mercurial 11.69 - has built-in support for several popular hosting technologies, 11.70 - most notably CGI (Common Gateway Interface), and WSGI (Web 11.71 - Services Gateway Interface). See <xref 11.72 - linkend="sec:collab:cgi"/> for details of CGI and WSGI 11.73 - configuration.</para> 11.74 - </sect1> 11.75 - 11.76 - <sect1> 11.77 - <title>Collaboration models</title> 11.78 - 11.79 - <para id="x_451">With a suitably flexible tool, making decisions about 11.80 - workflow is much more of a social engineering challenge than a 11.81 - technical one. Mercurial imposes few limitations on how you can 11.82 - structure the flow of work in a project, so it's up to you and 11.83 - your group to set up and live with a model that matches your own 11.84 - particular needs.</para> 11.85 - 11.86 - <sect2> 11.87 - <title>Factors to keep in mind</title> 11.88 - 11.89 - <para id="x_452">The most important aspect of any model that you must keep 11.90 - in mind is how well it matches the needs and capabilities of 11.91 - the people who will be using it. This might seem 11.92 - self-evident; even so, you still can't afford to forget it for 11.93 - a moment.</para> 11.94 - 11.95 - <para id="x_453">I once put together a workflow model that seemed to make 11.96 - perfect sense to me, but that caused a considerable amount of 11.97 - consternation and strife within my development team. In spite 11.98 - of my attempts to explain why we needed a complex set of 11.99 - branches, and how changes ought to flow between them, a few 11.100 - team members revolted. Even though they were smart people, 11.101 - they didn't want to pay attention to the constraints we were 11.102 - operating under, or face the consequences of those constraints 11.103 - in the details of the model that I was advocating.</para> 11.104 - 11.105 - <para id="x_454">Don't sweep foreseeable social or technical problems under 11.106 - the rug. Whatever scheme you put into effect, you should plan 11.107 - for mistakes and problem scenarios. Consider adding automated 11.108 - machinery to prevent, or quickly recover from, trouble that 11.109 - you can anticipate. As an example, if you intend to have a 11.110 - branch with not-for-release changes in it, you'd do well to 11.111 - think early about the possibility that someone might 11.112 - accidentally merge those changes into a release branch. You 11.113 - could avoid this particular problem by writing a hook that 11.114 - prevents changes from being merged from an inappropriate 11.115 - branch.</para> 11.116 - </sect2> 11.117 - 11.118 - <sect2> 11.119 - <title>Informal anarchy</title> 11.120 - 11.121 - <para id="x_455">I wouldn't suggest an <quote>anything goes</quote> 11.122 - approach as something sustainable, but it's a model that's 11.123 - easy to grasp, and it works perfectly well in a few unusual 11.124 - situations.</para> 11.125 - 11.126 - <para id="x_456">As one example, many projects have a loose-knit group of 11.127 - collaborators who rarely physically meet each other. Some 11.128 - groups like to overcome the isolation of working at a distance 11.129 - by organizing occasional <quote>sprints</quote>. In a sprint, 11.130 - a number of people get together in a single location (a 11.131 - company's conference room, a hotel meeting room, that kind of 11.132 - place) and spend several days more or less locked in there, 11.133 - hacking intensely on a handful of projects.</para> 11.134 - 11.135 - <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the 11.136 - <command role="hg-cmd">hg serve</command> command, since 11.137 - <command role="hg-cmd">hg serve</command> does not require any 11.138 - fancy server infrastructure. You can get started with 11.139 - <command role="hg-cmd">hg serve</command> in moments, by 11.140 - reading <xref linkend="sec:collab:serve"/> below. Then simply 11.141 - tell the person next to you that you're running a server, send 11.142 - the URL to them in an instant message, and you immediately 11.143 - have a quick-turnaround way to work together. They can type 11.144 - your URL into their web browser and quickly review your 11.145 - changes; or they can pull a bugfix from you and verify it; or 11.146 - they can clone a branch containing a new feature and try it 11.147 - out.</para> 11.148 - 11.149 - <para id="x_458">The charm, and the problem, with doing things 11.150 - in an ad hoc fashion like this is that only people who know 11.151 - about your changes, and where they are, can see them. Such an 11.152 - informal approach simply doesn't scale beyond a handful 11.153 - people, because each individual needs to know about 11.154 - <emphasis>n</emphasis> different repositories to pull 11.155 - from.</para> 11.156 - </sect2> 11.157 - 11.158 - <sect2> 11.159 - <title>A single central repository</title> 11.160 - 11.161 - <para id="x_459">For smaller projects migrating from a centralised revision 11.162 - control tool, perhaps the easiest way to get started is to 11.163 - have changes flow through a single shared central repository. 11.164 - This is also the most common <quote>building block</quote> for 11.165 - more ambitious workflow schemes.</para> 11.166 - 11.167 - <para id="x_45a">Contributors start by cloning a copy of this repository. 11.168 - They can pull changes from it whenever they need to, and some 11.169 - (perhaps all) developers have permission to push a change back 11.170 - when they're ready for other people to see it.</para> 11.171 - 11.172 - <para id="x_45b">Under this model, it can still often make sense for people 11.173 - to pull changes directly from each other, without going 11.174 - through the central repository. Consider a case in which I 11.175 - have a tentative bug fix, but I am worried that if I were to 11.176 - publish it to the central repository, it might subsequently 11.177 - break everyone else's trees as they pull it. To reduce the 11.178 - potential for damage, I can ask you to clone my repository 11.179 - into a temporary repository of your own and test it. This 11.180 - lets us put off publishing the potentially unsafe change until 11.181 - it has had a little testing.</para> 11.182 - 11.183 - <para id="x_45c">If a team is hosting its own repository in this 11.184 - kind of scenario, people will usually use the 11.185 - <command>ssh</command> protocol to securely push changes to 11.186 - the central repository, as documented in <xref 11.187 - linkend="sec:collab:ssh"/>. It's also usual to publish a 11.188 - read-only copy of the repository over HTTP, as in 11.189 - <xref linkend="sec:collab:cgi"/>. Publishing over HTTP 11.190 - satisfies the needs of people who don't have push access, and 11.191 - those who want to use web browsers to browse the repository's 11.192 - history.</para> 11.193 - </sect2> 11.194 - 11.195 - <sect2> 11.196 - <title>A hosted central repository</title> 11.197 - 11.198 - <para id="x_6a1">A wonderful thing about public hosting services like 11.199 - <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that 11.200 - not only do they handle the fiddly server configuration 11.201 - details, such as user accounts, authentication, and secure 11.202 - wire protocols, they provide additional infrastructure to make 11.203 - this model work well.</para> 11.204 - 11.205 - <para id="x_6a2">For instance, a well-engineered hosting service will let 11.206 - people clone their own copies of a repository with a single 11.207 - click. This lets people work in separate spaces and share 11.208 - their changes when they're ready.</para> 11.209 - 11.210 - <para id="x_6a3">In addition, a good hosting service will let people 11.211 - communicate with each other, for instance to say <quote>there 11.212 - are changes ready for you to review in this 11.213 - tree</quote>.</para> 11.214 - </sect2> 11.215 - 11.216 - <sect2> 11.217 - <title>Working with multiple branches</title> 11.218 - 11.219 - <para id="x_45d">Projects of any significant size naturally tend to make 11.220 - progress on several fronts simultaneously. In the case of 11.221 - software, it's common for a project to go through periodic 11.222 - official releases. A release might then go into 11.223 - <quote>maintenance mode</quote> for a while after its first 11.224 - publication; maintenance releases tend to contain only bug 11.225 - fixes, not new features. In parallel with these maintenance 11.226 - releases, one or more future releases may be under 11.227 - development. People normally use the word 11.228 - <quote>branch</quote> to refer to one of these many slightly 11.229 - different directions in which development is 11.230 - proceeding.</para> 11.231 - 11.232 - <para id="x_45e">Mercurial is particularly well suited to managing a number 11.233 - of simultaneous, but not identical, branches. Each 11.234 - <quote>development direction</quote> can live in its own 11.235 - central repository, and you can merge changes from one to 11.236 - another as the need arises. Because repositories are 11.237 - independent of each other, unstable changes in a development 11.238 - branch will never affect a stable branch unless someone 11.239 - explicitly merges those changes into the stable branch.</para> 11.240 - 11.241 - <para id="x_45f">Here's an example of how this can work in practice. Let's 11.242 - say you have one <quote>main branch</quote> on a central 11.243 - server.</para> 11.244 - 11.245 - &interaction.branching.init; 11.246 - 11.247 - <para id="x_460">People clone it, make changes locally, test them, and push 11.248 - them back.</para> 11.249 - 11.250 - <para id="x_461">Once the main branch reaches a release milestone, you can 11.251 - use the <command role="hg-cmd">hg tag</command> command to 11.252 - give a permanent name to the milestone revision.</para> 11.253 - 11.254 - &interaction.branching.tag; 11.255 - 11.256 - <para id="x_462">Let's say some ongoing 11.257 - development occurs on the main branch.</para> 11.258 - 11.259 - &interaction.branching.main; 11.260 - 11.261 - <para id="x_463">Using the tag that was recorded at the milestone, people 11.262 - who clone that repository at any time in the future can use 11.263 - <command role="hg-cmd">hg update</command> to get a copy of 11.264 - the working directory exactly as it was when that tagged 11.265 - revision was committed.</para> 11.266 - 11.267 - &interaction.branching.update; 11.268 - 11.269 - <para id="x_464">In addition, immediately after the main branch is tagged, 11.270 - we can then clone the main branch on the server to a new 11.271 - <quote>stable</quote> branch, also on the server.</para> 11.272 - 11.273 - &interaction.branching.clone; 11.274 - 11.275 - <para id="x_465">If we need to make a change to the stable 11.276 - branch, we can then clone <emphasis>that</emphasis> 11.277 - repository, make our changes, commit, and push our changes 11.278 - back there.</para> 11.279 - 11.280 - &interaction.branching.stable; 11.281 - 11.282 - <para id="x_466">Because Mercurial repositories are independent, and 11.283 - Mercurial doesn't move changes around automatically, the 11.284 - stable and main branches are <emphasis>isolated</emphasis> 11.285 - from each other. The changes that we made on the main branch 11.286 - don't <quote>leak</quote> to the stable branch, and vice 11.287 - versa.</para> 11.288 - 11.289 - <para id="x_467">We'll often want all of our bugfixes on the stable 11.290 - branch to show up on the main branch, too. Rather than 11.291 - rewrite a bugfix on the main branch, we can simply pull and 11.292 - merge changes from the stable to the main branch, and 11.293 - Mercurial will bring those bugfixes in for us.</para> 11.294 - 11.295 - &interaction.branching.merge; 11.296 - 11.297 - <para id="x_468">The main branch will still contain changes that 11.298 - are not on the stable branch, but it will also contain all of 11.299 - the bugfixes from the stable branch. The stable branch 11.300 - remains unaffected by these changes, since changes are only 11.301 - flowing from the stable to the main branch, and not the other 11.302 - way.</para> 11.303 - </sect2> 11.304 - 11.305 - <sect2> 11.306 - <title>Feature branches</title> 11.307 - 11.308 - <para id="x_469">For larger projects, an effective way to manage change is 11.309 - to break up a team into smaller groups. Each group has a 11.310 - shared branch of its own, cloned from a single 11.311 - <quote>master</quote> branch used by the entire project. 11.312 - People working on an individual branch are typically quite 11.313 - isolated from developments on other branches.</para> 11.314 - 11.315 - <figure id="fig:collab:feature-branches"> 11.316 - <title>Feature branches</title> 11.317 - <mediaobject> 11.318 - <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject> 11.319 - <textobject><phrase>XXX add text</phrase></textobject> 11.320 - </mediaobject> 11.321 - </figure> 11.322 - 11.323 - <para id="x_46b">When a particular feature is deemed to be in suitable 11.324 - shape, someone on that feature team pulls and merges from the 11.325 - master branch into the feature branch, then pushes back up to 11.326 - the master branch.</para> 11.327 - </sect2> 11.328 - 11.329 - <sect2> 11.330 - <title>The release train</title> 11.331 - 11.332 - <para id="x_46c">Some projects are organized on a <quote>train</quote> 11.333 - basis: a release is scheduled to happen every few months, and 11.334 - whatever features are ready when the <quote>train</quote> is 11.335 - ready to leave are allowed in.</para> 11.336 - 11.337 - <para id="x_46d">This model resembles working with feature branches. The 11.338 - difference is that when a feature branch misses a train, 11.339 - someone on the feature team pulls and merges the changes that 11.340 - went out on that train release into the feature branch, and 11.341 - the team continues its work on top of that release so that 11.342 - their feature can make the next release.</para> 11.343 - </sect2> 11.344 - 11.345 - <sect2> 11.346 - <title>The Linux kernel model</title> 11.347 - 11.348 - <para id="x_46e">The development of the Linux kernel has a shallow 11.349 - hierarchical structure, surrounded by a cloud of apparent 11.350 - chaos. Because most Linux developers use 11.351 - <command>git</command>, a distributed revision control tool 11.352 - with capabilities similar to Mercurial, it's useful to 11.353 - describe the way work flows in that environment; if you like 11.354 - the ideas, the approach translates well across tools.</para> 11.355 - 11.356 - <para id="x_46f">At the center of the community sits Linus Torvalds, the 11.357 - creator of Linux. He publishes a single source repository 11.358 - that is considered the <quote>authoritative</quote> current 11.359 - tree by the entire developer community. Anyone can clone 11.360 - Linus's tree, but he is very choosy about whose trees he pulls 11.361 - from.</para> 11.362 - 11.363 - <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>. 11.364 - As a general rule, he pulls whatever changes they publish, in 11.365 - most cases without even reviewing those changes. Some of 11.366 - those lieutenants are generally agreed to be 11.367 - <quote>maintainers</quote>, responsible for specific 11.368 - subsystems within the kernel. If a random kernel hacker wants 11.369 - to make a change to a subsystem that they want to end up in 11.370 - Linus's tree, they must find out who the subsystem's 11.371 - maintainer is, and ask that maintainer to take their change. 11.372 - If the maintainer reviews their changes and agrees to take 11.373 - them, they'll pass them along to Linus in due course.</para> 11.374 - 11.375 - <para id="x_471">Individual lieutenants have their own approaches to 11.376 - reviewing, accepting, and publishing changes; and for deciding 11.377 - when to feed them to Linus. In addition, there are several 11.378 - well known branches that people use for different purposes. 11.379 - For example, a few people maintain <quote>stable</quote> 11.380 - repositories of older versions of the kernel, to which they 11.381 - apply critical fixes as needed. Some maintainers publish 11.382 - multiple trees: one for experimental changes; one for changes 11.383 - that they are about to feed upstream; and so on. Others just 11.384 - publish a single tree.</para> 11.385 - 11.386 - <para id="x_472">This model has two notable features. The first is that 11.387 - it's <quote>pull only</quote>. You have to ask, convince, or 11.388 - beg another developer to take a change from you, because there 11.389 - are almost no trees to which more than one person can push, 11.390 - and there's no way to push changes into a tree that someone 11.391 - else controls.</para> 11.392 - 11.393 - <para id="x_473">The second is that it's based on reputation and acclaim. 11.394 - If you're an unknown, Linus will probably ignore changes from 11.395 - you without even responding. But a subsystem maintainer will 11.396 - probably review them, and will likely take them if they pass 11.397 - their criteria for suitability. The more <quote>good</quote> 11.398 - changes you contribute to a maintainer, the more likely they 11.399 - are to trust your judgment and accept your changes. If you're 11.400 - well-known and maintain a long-lived branch for something 11.401 - Linus hasn't yet accepted, people with similar interests may 11.402 - pull your changes regularly to keep up with your work.</para> 11.403 - 11.404 - <para id="x_474">Reputation and acclaim don't necessarily cross subsystem 11.405 - or <quote>people</quote> boundaries. If you're a respected 11.406 - but specialised storage hacker, and you try to fix a 11.407 - networking bug, that change will receive a level of scrutiny 11.408 - from a network maintainer comparable to a change from a 11.409 - complete stranger.</para> 11.410 - 11.411 - <para id="x_475">To people who come from more orderly project backgrounds, 11.412 - the comparatively chaotic Linux kernel development process 11.413 - often seems completely insane. It's subject to the whims of 11.414 - individuals; people make sweeping changes whenever they deem 11.415 - it appropriate; and the pace of development is astounding. 11.416 - And yet Linux is a highly successful, well-regarded piece of 11.417 - software.</para> 11.418 - </sect2> 11.419 - 11.420 - <sect2> 11.421 - <title>Pull-only versus shared-push collaboration</title> 11.422 - 11.423 - <para id="x_476">A perpetual source of heat in the open source community is 11.424 - whether a development model in which people only ever pull 11.425 - changes from others is <quote>better than</quote> one in which 11.426 - multiple people can push changes to a shared 11.427 - repository.</para> 11.428 - 11.429 - <para id="x_477">Typically, the backers of the shared-push model use tools 11.430 - that actively enforce this approach. If you're using a 11.431 - centralised revision control tool such as Subversion, there's 11.432 - no way to make a choice over which model you'll use: the tool 11.433 - gives you shared-push, and if you want to do anything else, 11.434 - you'll have to roll your own approach on top (such as applying 11.435 - a patch by hand).</para> 11.436 - 11.437 - <para id="x_478">A good distributed revision control tool will 11.438 - support both models. You and your collaborators can then 11.439 - structure how you work together based on your own needs and 11.440 - preferences, not on what contortions your tools force you 11.441 - into.</para> 11.442 - </sect2> 11.443 - <sect2> 11.444 - <title>Where collaboration meets branch management</title> 11.445 - 11.446 - <para id="x_479">Once you and your team set up some shared 11.447 - repositories and start propagating changes back and forth 11.448 - between local and shared repos, you begin to face a related, 11.449 - but slightly different challenge: that of managing the 11.450 - multiple directions in which your team may be moving at once. 11.451 - Even though this subject is intimately related to how your 11.452 - team collaborates, it's dense enough to merit treatment of its 11.453 - own, in <xref linkend="chap:branch"/>.</para> 11.454 - </sect2> 11.455 - </sect1> 11.456 - 11.457 - <sect1> 11.458 - <title>The technical side of sharing</title> 11.459 - 11.460 - <para id="x_47a">The remainder of this chapter is devoted to the question of 11.461 - sharing changes with your collaborators.</para> 11.462 - </sect1> 11.463 - 11.464 - <sect1 id="sec:collab:serve"> 11.465 - <title>Informal sharing with <command role="hg-cmd">hg 11.466 - serve</command></title> 11.467 - 11.468 - <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command> 11.469 - command is wonderfully suited to small, tight-knit, and 11.470 - fast-paced group environments. It also provides a great way to 11.471 - get a feel for using Mercurial commands over a network.</para> 11.472 - 11.473 - <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a 11.474 - repository, and in under a second it will bring up a specialised 11.475 - HTTP server; this will accept connections from any client, and 11.476 - serve up data for that repository until you terminate it. 11.477 - Anyone who knows the URL of the server you just started, and can 11.478 - talk to your computer over the network, can then use a web 11.479 - browser or Mercurial to read data from that repository. A URL 11.480 - for a <command role="hg-cmd">hg serve</command> instance running 11.481 - on a laptop is likely to look something like 11.482 - <literal>http://my-laptop.local:8000/</literal>.</para> 11.483 - 11.484 - <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is 11.485 - <emphasis>not</emphasis> a general-purpose web server. It can do 11.486 - only two things:</para> 11.487 - <itemizedlist> 11.488 - <listitem><para id="x_47e">Allow people to browse the history of the 11.489 - repository it's serving, from their normal web 11.490 - browsers.</para> 11.491 - </listitem> 11.492 - <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people 11.493 - can <command role="hg-cmd">hg clone</command> or <command 11.494 - role="hg-cmd">hg pull</command> changes from that 11.495 - repository.</para> 11.496 - </listitem></itemizedlist> 11.497 - <para id="x_480">In particular, <command role="hg-cmd">hg serve</command> 11.498 - won't allow remote users to <emphasis>modify</emphasis> your 11.499 - repository. It's intended for read-only use.</para> 11.500 - 11.501 - <para id="x_481">If you're getting started with Mercurial, there's nothing to 11.502 - prevent you from using <command role="hg-cmd">hg serve</command> 11.503 - to serve up a repository on your own computer, then use commands 11.504 - like <command role="hg-cmd">hg clone</command>, <command 11.505 - role="hg-cmd">hg incoming</command>, and so on to talk to that 11.506 - server as if the repository was hosted remotely. This can help 11.507 - you to quickly get acquainted with using commands on 11.508 - network-hosted repositories.</para> 11.509 - 11.510 - <sect2> 11.511 - <title>A few things to keep in mind</title> 11.512 - 11.513 - <para id="x_482">Because it provides unauthenticated read access to all 11.514 - clients, you should only use <command role="hg-cmd">hg 11.515 - serve</command> in an environment where you either don't 11.516 - care, or have complete control over, who can access your 11.517 - network and pull data from your repository.</para> 11.518 - 11.519 - <para id="x_483">The <command role="hg-cmd">hg serve</command> command 11.520 - knows nothing about any firewall software you might have 11.521 - installed on your system or network. It cannot detect or 11.522 - control your firewall software. If other people are unable to 11.523 - talk to a running <command role="hg-cmd">hg serve</command> 11.524 - instance, the second thing you should do 11.525 - (<emphasis>after</emphasis> you make sure that they're using 11.526 - the correct URL) is check your firewall configuration.</para> 11.527 - 11.528 - <para id="x_484">By default, <command role="hg-cmd">hg serve</command> 11.529 - listens for incoming connections on port 8000. If another 11.530 - process is already listening on the port you want to use, you 11.531 - can specify a different port to listen on using the <option 11.532 - role="hg-opt-serve">-p</option> option.</para> 11.533 - 11.534 - <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command> 11.535 - starts, it prints no output, which can be a bit unnerving. If 11.536 - you'd like to confirm that it is indeed running correctly, and 11.537 - find out what URL you should send to your collaborators, start 11.538 - it with the <option role="hg-opt-global">-v</option> 11.539 - option.</para> 11.540 - </sect2> 11.541 - </sect1> 11.542 - 11.543 - <sect1 id="sec:collab:ssh"> 11.544 - <title>Using the Secure Shell (ssh) protocol</title> 11.545 - 11.546 - <para id="x_486">You can pull and push changes securely over a network 11.547 - connection using the Secure Shell (<literal>ssh</literal>) 11.548 - protocol. To use this successfully, you may have to do a little 11.549 - bit of configuration on the client or server sides.</para> 11.550 - 11.551 - <para id="x_487">If you're not familiar with ssh, it's the name of 11.552 - both a command and a network protocol that let you securely 11.553 - communicate with another computer. To use it with Mercurial, 11.554 - you'll be setting up one or more user accounts on a server so 11.555 - that remote users can log in and execute commands.</para> 11.556 - 11.557 - <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll 11.558 - probably find some of the material that follows to be elementary 11.559 - in nature.)</para> 11.560 - 11.561 - <sect2> 11.562 - <title>How to read and write ssh URLs</title> 11.563 - 11.564 - <para id="x_489">An ssh URL tends to look like this:</para> 11.565 - <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting> 11.566 - <orderedlist> 11.567 - <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote> 11.568 - part tells Mercurial to use the ssh protocol.</para> 11.569 - </listitem> 11.570 - <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote> 11.571 - component indicates what username to log into the server 11.572 - as. You can leave this out if the remote username is the 11.573 - same as your local username.</para> 11.574 - </listitem> 11.575 - <listitem><para id="x_48c">The 11.576 - <quote><literal>hg.serpentine.com</literal></quote> gives 11.577 - the hostname of the server to log into.</para> 11.578 - </listitem> 11.579 - <listitem><para id="x_48d">The <quote>:22</quote> identifies the port 11.580 - number to connect to the server on. The default port is 11.581 - 22, so you only need to specify a colon and port number if 11.582 - you're <emphasis>not</emphasis> using port 22.</para> 11.583 - </listitem> 11.584 - <listitem><para id="x_48e">The remainder of the URL is the local path to 11.585 - the repository on the server.</para> 11.586 - </listitem></orderedlist> 11.587 - 11.588 - <para id="x_48f">There's plenty of scope for confusion with the path 11.589 - component of ssh URLs, as there is no standard way for tools 11.590 - to interpret it. Some programs behave differently than others 11.591 - when dealing with these paths. This isn't an ideal situation, 11.592 - but it's unlikely to change. Please read the following 11.593 - paragraphs carefully.</para> 11.594 - 11.595 - <para id="x_490">Mercurial treats the path to a repository on the server as 11.596 - relative to the remote user's home directory. For example, if 11.597 - user <literal>foo</literal> on the server has a home directory 11.598 - of <filename class="directory">/home/foo</filename>, then an 11.599 - ssh URL that contains a path component of <filename 11.600 - class="directory">bar</filename> <emphasis>really</emphasis> 11.601 - refers to the directory <filename 11.602 - class="directory">/home/foo/bar</filename>.</para> 11.603 - 11.604 - <para id="x_491">If you want to specify a path relative to another user's 11.605 - home directory, you can use a path that starts with a tilde 11.606 - character followed by the user's name (let's call them 11.607 - <literal>otheruser</literal>), like this.</para> 11.608 - <programlisting>ssh://server/~otheruser/hg/repo</programlisting> 11.609 - 11.610 - <para id="x_492">And if you really want to specify an 11.611 - <emphasis>absolute</emphasis> path on the server, begin the 11.612 - path component with two slashes, as in this example.</para> 11.613 - <programlisting>ssh://server//absolute/path</programlisting> 11.614 - </sect2> 11.615 - 11.616 - <sect2> 11.617 - <title>Finding an ssh client for your system</title> 11.618 - 11.619 - <para id="x_493">Almost every Unix-like system comes with OpenSSH 11.620 - preinstalled. If you're using such a system, run 11.621 - <literal>which ssh</literal> to find out if the 11.622 - <command>ssh</command> command is installed (it's usually in 11.623 - <filename class="directory">/usr/bin</filename>). In the 11.624 - unlikely event that it isn't present, take a look at your 11.625 - system documentation to figure out how to install it.</para> 11.626 - 11.627 - <para id="x_494">On Windows, the TortoiseHg package is bundled 11.628 - with a version of Simon Tatham's excellent 11.629 - <command>plink</command> command, and you should not need to 11.630 - do any further configuration.</para> 11.631 - </sect2> 11.632 - 11.633 - <sect2> 11.634 - <title>Generating a key pair</title> 11.635 - 11.636 - <para id="x_499">To avoid the need to repetitively type a 11.637 - password every time you need to use your ssh client, I 11.638 - recommend generating a key pair.</para> 11.639 - 11.640 - <tip> 11.641 - <title>Key pairs are not mandatory</title> 11.642 - 11.643 - <para id="x_6a4">Mercurial knows nothing about ssh authentication or key 11.644 - pairs. You can, if you like, safely ignore this section and 11.645 - the one that follows until you grow tired of repeatedly 11.646 - typing ssh passwords.</para> 11.647 - </tip> 11.648 - 11.649 - <itemizedlist> 11.650 - <listitem> 11.651 - <para id="x_6a5">On a Unix-like system, the 11.652 - <command>ssh-keygen</command> command will do the 11.653 - trick.</para> 11.654 - <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need 11.655 - to download a command named <command>puttygen</command> 11.656 - from <ulink 11.657 - url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 11.658 - PuTTY web site</ulink> to generate a key pair. See 11.659 - <ulink 11.660 - url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 11.661 - <command>puttygen</command> documentation</ulink> for 11.662 - details of how use the command.</para> 11.663 - </listitem> 11.664 - </itemizedlist> 11.665 - 11.666 - <para id="x_49a">When you generate a key pair, it's usually 11.667 - <emphasis>highly</emphasis> advisable to protect it with a 11.668 - passphrase. (The only time that you might not want to do this 11.669 - is when you're using the ssh protocol for automated tasks on a 11.670 - secure network.)</para> 11.671 - 11.672 - <para id="x_49b">Simply generating a key pair isn't enough, however. 11.673 - You'll need to add the public key to the set of authorised 11.674 - keys for whatever user you're logging in remotely as. For 11.675 - servers using OpenSSH (the vast majority), this will mean 11.676 - adding the public key to a list in a file called <filename 11.677 - role="special">authorized_keys</filename> in their <filename 11.678 - role="special" class="directory">.ssh</filename> 11.679 - directory.</para> 11.680 - 11.681 - <para id="x_49c">On a Unix-like system, your public key will have a 11.682 - <filename>.pub</filename> extension. If you're using 11.683 - <command>puttygen</command> on Windows, you can save the 11.684 - public key to a file of your choosing, or paste it from the 11.685 - window it's displayed in straight into the <filename 11.686 - role="special">authorized_keys</filename> file.</para> 11.687 - </sect2> 11.688 - <sect2> 11.689 - <title>Using an authentication agent</title> 11.690 - 11.691 - <para id="x_49d">An authentication agent is a daemon that stores 11.692 - passphrases in memory (so it will forget passphrases if you 11.693 - log out and log back in again). An ssh client will notice if 11.694 - it's running, and query it for a passphrase. If there's no 11.695 - authentication agent running, or the agent doesn't store the 11.696 - necessary passphrase, you'll have to type your passphrase 11.697 - every time Mercurial tries to communicate with a server on 11.698 - your behalf (e.g. whenever you pull or push changes).</para> 11.699 - 11.700 - <para id="x_49e">The downside of storing passphrases in an agent is that 11.701 - it's possible for a well-prepared attacker to recover the 11.702 - plain text of your passphrases, in some cases even if your 11.703 - system has been power-cycled. You should make your own 11.704 - judgment as to whether this is an acceptable risk. It 11.705 - certainly saves a lot of repeated typing.</para> 11.706 - 11.707 - <itemizedlist> 11.708 - <listitem> 11.709 - <para id="x_49f">On Unix-like systems, the agent is called 11.710 - <command>ssh-agent</command>, and it's often run 11.711 - automatically for you when you log in. You'll need to use 11.712 - the <command>ssh-add</command> command to add passphrases 11.713 - to the agent's store.</para> 11.714 - </listitem> 11.715 - <listitem> 11.716 - <para id="x_6a7">On Windows, if you're using TortoiseHg, the 11.717 - <command>pageant</command> command acts as the agent. As 11.718 - with <command>puttygen</command>, you'll need to <ulink 11.719 - url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 11.720 - <command>pageant</command></ulink> from the PuTTY web 11.721 - site and read <ulink 11.722 - url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 11.723 - documentation</ulink>. The <command>pageant</command> 11.724 - command adds an icon to your system tray that will let you 11.725 - manage stored passphrases.</para> 11.726 - </listitem> 11.727 - </itemizedlist> 11.728 - </sect2> 11.729 - 11.730 - <sect2> 11.731 - <title>Configuring the server side properly</title> 11.732 - 11.733 - <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it, 11.734 - a variety of things can go wrong. Add Mercurial 11.735 - on top, and there's plenty more scope for head-scratching. 11.736 - Most of these potential problems occur on the server side, not 11.737 - the client side. The good news is that once you've gotten a 11.738 - configuration working, it will usually continue to work 11.739 - indefinitely.</para> 11.740 - 11.741 - <para id="x_4a1">Before you try using Mercurial to talk to an ssh server, 11.742 - it's best to make sure that you can use the normal 11.743 - <command>ssh</command> or <command>putty</command> command to 11.744 - talk to the server first. If you run into problems with using 11.745 - these commands directly, Mercurial surely won't work. Worse, 11.746 - it will obscure the underlying problem. Any time you want to 11.747 - debug ssh-related Mercurial problems, you should drop back to 11.748 - making sure that plain ssh client commands work first, 11.749 - <emphasis>before</emphasis> you worry about whether there's a 11.750 - problem with Mercurial.</para> 11.751 - 11.752 - <para id="x_4a2">The first thing to be sure of on the server side is that 11.753 - you can actually log in from another machine at all. If you 11.754 - can't use <command>ssh</command> or <command>putty</command> 11.755 - to log in, the error message you get may give you a few hints 11.756 - as to what's wrong. The most common problems are as 11.757 - follows.</para> 11.758 - <itemizedlist> 11.759 - <listitem><para id="x_4a3">If you get a <quote>connection refused</quote> 11.760 - error, either there isn't an SSH daemon running on the 11.761 - server at all, or it's inaccessible due to firewall 11.762 - configuration.</para> 11.763 - </listitem> 11.764 - <listitem><para id="x_4a4">If you get a <quote>no route to host</quote> 11.765 - error, you either have an incorrect address for the server 11.766 - or a seriously locked down firewall that won't admit its 11.767 - existence at all.</para> 11.768 - </listitem> 11.769 - <listitem><para id="x_4a5">If you get a <quote>permission denied</quote> 11.770 - error, you may have mistyped the username on the server, 11.771 - or you could have mistyped your key's passphrase or the 11.772 - remote user's password.</para> 11.773 - </listitem></itemizedlist> 11.774 - <para id="x_4a6">In summary, if you're having trouble talking to the 11.775 - server's ssh daemon, first make sure that one is running at 11.776 - all. On many systems it will be installed, but disabled, by 11.777 - default. Once you're done with this step, you should then 11.778 - check that the server's firewall is configured to allow 11.779 - incoming connections on the port the ssh daemon is listening 11.780 - on (usually 22). Don't worry about more exotic possibilities 11.781 - for misconfiguration until you've checked these two 11.782 - first.</para> 11.783 - 11.784 - <para id="x_4a7">If you're using an authentication agent on the client side 11.785 - to store passphrases for your keys, you ought to be able to 11.786 - log into the server without being prompted for a passphrase or 11.787 - a password. If you're prompted for a passphrase, there are a 11.788 - few possible culprits.</para> 11.789 - <itemizedlist> 11.790 - <listitem><para id="x_4a8">You might have forgotten to use 11.791 - <command>ssh-add</command> or <command>pageant</command> 11.792 - to store the passphrase.</para> 11.793 - </listitem> 11.794 - <listitem><para id="x_4a9">You might have stored the passphrase for the 11.795 - wrong key.</para> 11.796 - </listitem></itemizedlist> 11.797 - <para id="x_4aa">If you're being prompted for the remote user's password, 11.798 - there are another few possible problems to check.</para> 11.799 - <itemizedlist> 11.800 - <listitem><para id="x_4ab">Either the user's home directory or their 11.801 - <filename role="special" class="directory">.ssh</filename> 11.802 - directory might have excessively liberal permissions. As 11.803 - a result, the ssh daemon will not trust or read their 11.804 - <filename role="special">authorized_keys</filename> file. 11.805 - For example, a group-writable home or <filename 11.806 - role="special" class="directory">.ssh</filename> 11.807 - directory will often cause this symptom.</para> 11.808 - </listitem> 11.809 - <listitem><para id="x_4ac">The user's <filename 11.810 - role="special">authorized_keys</filename> file may have 11.811 - a problem. If anyone other than the user owns or can write 11.812 - to that file, the ssh daemon will not trust or read 11.813 - it.</para> 11.814 - </listitem></itemizedlist> 11.815 - 11.816 - <para id="x_4ad">In the ideal world, you should be able to run the 11.817 - following command successfully, and it should print exactly 11.818 - one line of output, the current date and time.</para> 11.819 - <programlisting>ssh myserver date</programlisting> 11.820 - 11.821 - <para id="x_4ae">If, on your server, you have login scripts that print 11.822 - banners or other junk even when running non-interactive 11.823 - commands like this, you should fix them before you continue, 11.824 - so that they only print output if they're run interactively. 11.825 - Otherwise these banners will at least clutter up Mercurial's 11.826 - output. Worse, they could potentially cause problems with 11.827 - running Mercurial commands remotely. Mercurial tries to 11.828 - detect and ignore banners in non-interactive 11.829 - <command>ssh</command> sessions, but it is not foolproof. (If 11.830 - you're editing your login scripts on your server, the usual 11.831 - way to see if a login script is running in an interactive 11.832 - shell is to check the return code from the command 11.833 - <literal>tty -s</literal>.)</para> 11.834 - 11.835 - <para id="x_4af">Once you've verified that plain old ssh is working with 11.836 - your server, the next step is to ensure that Mercurial runs on 11.837 - the server. The following command should run 11.838 - successfully:</para> 11.839 - 11.840 - <programlisting>ssh myserver hg version</programlisting> 11.841 - 11.842 - <para id="x_4b0">If you see an error message instead of normal <command 11.843 - role="hg-cmd">hg version</command> output, this is usually 11.844 - because you haven't installed Mercurial to <filename 11.845 - class="directory">/usr/bin</filename>. Don't worry if this 11.846 - is the case; you don't need to do that. But you should check 11.847 - for a few possible problems.</para> 11.848 - <itemizedlist> 11.849 - <listitem><para id="x_4b1">Is Mercurial really installed on the server at 11.850 - all? I know this sounds trivial, but it's worth 11.851 - checking!</para> 11.852 - </listitem> 11.853 - <listitem><para id="x_4b2">Maybe your shell's search path (usually set 11.854 - via the <envar>PATH</envar> environment variable) is 11.855 - simply misconfigured.</para> 11.856 - </listitem> 11.857 - <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment 11.858 - variable is only being set to point to the location of the 11.859 - <command>hg</command> executable if the login session is 11.860 - interactive. This can happen if you're setting the path 11.861 - in the wrong shell login script. See your shell's 11.862 - documentation for details.</para> 11.863 - </listitem> 11.864 - <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment 11.865 - variable may need to contain the path to the Mercurial 11.866 - Python modules. It might not be set at all; it could be 11.867 - incorrect; or it may be set only if the login is 11.868 - interactive.</para> 11.869 - </listitem></itemizedlist> 11.870 - 11.871 - <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command> 11.872 - over an ssh connection, well done! You've got the server and 11.873 - client sorted out. You should now be able to use Mercurial to 11.874 - access repositories hosted by that username on that server. 11.875 - If you run into problems with Mercurial and ssh at this point, 11.876 - try using the <option role="hg-opt-global">--debug</option> 11.877 - option to get a clearer picture of what's going on.</para> 11.878 - </sect2> 11.879 - <sect2> 11.880 - <title>Using compression with ssh</title> 11.881 - 11.882 - <para id="x_4b6">Mercurial does not compress data when it uses the ssh 11.883 - protocol, because the ssh protocol can transparently compress 11.884 - data. However, the default behavior of ssh clients is 11.885 - <emphasis>not</emphasis> to request compression.</para> 11.886 - 11.887 - <para id="x_4b7">Over any network other than a fast LAN (even a wireless 11.888 - network), using compression is likely to significantly speed 11.889 - up Mercurial's network operations. For example, over a WAN, 11.890 - someone measured compression as reducing the amount of time 11.891 - required to clone a particularly large repository from 51 11.892 - minutes to 17 minutes.</para> 11.893 - 11.894 - <para id="x_4b8">Both <command>ssh</command> and <command>plink</command> 11.895 - accept a <option role="cmd-opt-ssh">-C</option> option which 11.896 - turns on compression. You can easily edit your <filename 11.897 - role="special">~/.hgrc</filename> to enable compression for 11.898 - all of Mercurial's uses of the ssh protocol. Here is how to 11.899 - do so for regular <command>ssh</command> on Unix-like systems, 11.900 - for example.</para> 11.901 - <programlisting>[ui] 11.902 -ssh = ssh -C</programlisting> 11.903 - 11.904 - <para id="x_4b9">If you use <command>ssh</command> on a 11.905 - Unix-like system, you can configure it to always use 11.906 - compression when talking to your server. To do this, edit 11.907 - your <filename role="special">.ssh/config</filename> file 11.908 - (which may not yet exist), as follows.</para> 11.909 - 11.910 - <programlisting>Host hg 11.911 - Compression yes 11.912 - HostName hg.example.com</programlisting> 11.913 - 11.914 - <para id="x_4ba">This defines a hostname alias, 11.915 - <literal>hg</literal>. When you use that hostname on the 11.916 - <command>ssh</command> command line or in a Mercurial 11.917 - <literal>ssh</literal>-protocol URL, it will cause 11.918 - <command>ssh</command> to connect to 11.919 - <literal>hg.example.com</literal> and use compression. This 11.920 - gives you both a shorter name to type and compression, each of 11.921 - which is a good thing in its own right.</para> 11.922 - </sect2> 11.923 - </sect1> 11.924 - 11.925 - <sect1 id="sec:collab:cgi"> 11.926 - <title>Serving over HTTP using CGI</title> 11.927 - 11.928 - <para id="x_6a8">The simplest way to host one or more repositories in a 11.929 - permanent way is to use a web server and Mercurial's CGI 11.930 - support.</para> 11.931 - 11.932 - <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's 11.933 - CGI interface can take anything from a few moments to several 11.934 - hours.</para> 11.935 - 11.936 - <para id="x_4bc">We'll begin with the simplest of examples, and work our way 11.937 - towards a more complex configuration. Even for the most basic 11.938 - case, you're almost certainly going to need to read and modify 11.939 - your web server's configuration.</para> 11.940 - 11.941 - <note> 11.942 - <title>High pain tolerance required</title> 11.943 - 11.944 - <para id="x_4bd">Configuring a web server is a complex, fiddly, 11.945 - and highly system-dependent activity. I can't possibly give 11.946 - you instructions that will cover anything like all of the 11.947 - cases you will encounter. Please use your discretion and 11.948 - judgment in following the sections below. Be prepared to make 11.949 - plenty of mistakes, and to spend a lot of time reading your 11.950 - server's error logs.</para> 11.951 - 11.952 - <para id="x_6a9">If you don't have a strong stomach for tweaking 11.953 - configurations over and over, or a compelling need to host 11.954 - your own services, you might want to try one of the public 11.955 - hosting services that I mentioned earlier.</para> 11.956 - </note> 11.957 - 11.958 - <sect2> 11.959 - <title>Web server configuration checklist</title> 11.960 - 11.961 - <para id="x_4be">Before you continue, do take a few moments to check a few 11.962 - aspects of your system's setup.</para> 11.963 - 11.964 - <orderedlist> 11.965 - <listitem><para id="x_4bf">Do you have a web server installed 11.966 - at all? Mac OS X and some Linux distributions ship with 11.967 - Apache, but many other systems may not have a web server 11.968 - installed.</para> 11.969 - </listitem> 11.970 - <listitem><para id="x_4c0">If you have a web server installed, is it 11.971 - actually running? On most systems, even if one is 11.972 - present, it will be disabled by default.</para> 11.973 - </listitem> 11.974 - <listitem><para id="x_4c1">Is your server configured to allow you to run 11.975 - CGI programs in the directory where you plan to do so? 11.976 - Most servers default to explicitly disabling the ability 11.977 - to run CGI programs.</para> 11.978 - </listitem></orderedlist> 11.979 - 11.980 - <para id="x_4c2">If you don't have a web server installed, and don't have 11.981 - substantial experience configuring Apache, you should consider 11.982 - using the <literal>lighttpd</literal> web server instead of 11.983 - Apache. Apache has a well-deserved reputation for baroque and 11.984 - confusing configuration. While <literal>lighttpd</literal> is 11.985 - less capable in some ways than Apache, most of these 11.986 - capabilities are not relevant to serving Mercurial 11.987 - repositories. And <literal>lighttpd</literal> is undeniably 11.988 - <emphasis>much</emphasis> easier to get started with than 11.989 - Apache.</para> 11.990 - </sect2> 11.991 - 11.992 - <sect2> 11.993 - <title>Basic CGI configuration</title> 11.994 - 11.995 - <para id="x_4c3">On Unix-like systems, it's common for users to have a 11.996 - subdirectory named something like <filename 11.997 - class="directory">public_html</filename> in their home 11.998 - directory, from which they can serve up web pages. A file 11.999 - named <filename>foo</filename> in this directory will be 11.1000 - accessible at a URL of the form 11.1001 - <literal>http://www.example.com/username/foo</literal>.</para> 11.1002 - 11.1003 - <para id="x_4c4">To get started, find the <filename 11.1004 - role="special">hgweb.cgi</filename> script that should be 11.1005 - present in your Mercurial installation. If you can't quickly 11.1006 - find a local copy on your system, simply download one from the 11.1007 - master Mercurial repository at <ulink 11.1008 - url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>.</para> 11.1009 - 11.1010 - <para id="x_4c5">You'll need to copy this script into your <filename 11.1011 - class="directory">public_html</filename> directory, and 11.1012 - ensure that it's executable.</para> 11.1013 - <programlisting>cp .../hgweb.cgi ~/public_html 11.1014 -chmod 755 ~/public_html/hgweb.cgi</programlisting> 11.1015 - <para id="x_4c6">The <literal>755</literal> argument to 11.1016 - <command>chmod</command> is a little more general than just 11.1017 - making the script executable: it ensures that the script is 11.1018 - executable by anyone, and that <quote>group</quote> and 11.1019 - <quote>other</quote> write permissions are 11.1020 - <emphasis>not</emphasis> set. If you were to leave those 11.1021 - write permissions enabled, Apache's <literal>suexec</literal> 11.1022 - subsystem would likely refuse to execute the script. In fact, 11.1023 - <literal>suexec</literal> also insists that the 11.1024 - <emphasis>directory</emphasis> in which the script resides 11.1025 - must not be writable by others.</para> 11.1026 - <programlisting>chmod 755 ~/public_html</programlisting> 11.1027 - 11.1028 - <sect3 id="sec:collab:wtf"> 11.1029 - <title>What could <emphasis>possibly</emphasis> go 11.1030 - wrong?</title> 11.1031 - 11.1032 - <para id="x_4c7">Once you've copied the CGI script into place, 11.1033 - go into a web browser, and try to open the URL 11.1034 - <literal>http://myhostname/~myuser/hgweb.cgi</literal>, 11.1035 - <emphasis>but</emphasis> brace yourself for instant failure. 11.1036 - There's a high probability that trying to visit this URL 11.1037 - will fail, and there are many possible reasons for this. In 11.1038 - fact, you're likely to stumble over almost every one of the 11.1039 - possible errors below, so please read carefully. The 11.1040 - following are all of the problems I ran into on a system 11.1041 - running Fedora 7, with a fresh installation of Apache, and a 11.1042 - user account that I created specially to perform this 11.1043 - exercise.</para> 11.1044 - 11.1045 - <para id="x_4c8">Your web server may have per-user directories disabled. 11.1046 - If you're using Apache, search your config file for a 11.1047 - <literal>UserDir</literal> directive. If there's none 11.1048 - present, per-user directories will be disabled. If one 11.1049 - exists, but its value is <literal>disabled</literal>, then 11.1050 - per-user directories will be disabled. Otherwise, the 11.1051 - string after <literal>UserDir</literal> gives the name of 11.1052 - the subdirectory that Apache will look in under your home 11.1053 - directory, for example <filename 11.1054 - class="directory">public_html</filename>.</para> 11.1055 - 11.1056 - <para id="x_4c9">Your file access permissions may be too restrictive. 11.1057 - The web server must be able to traverse your home directory 11.1058 - and directories under your <filename 11.1059 - class="directory">public_html</filename> directory, and 11.1060 - read files under the latter too. Here's a quick recipe to 11.1061 - help you to make your permissions more appropriate.</para> 11.1062 - <programlisting>chmod 755 ~ 11.1063 -find ~/public_html -type d -print0 | xargs -0r chmod 755 11.1064 -find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting> 11.1065 - 11.1066 - <para id="x_4ca">The other possibility with permissions is that you might 11.1067 - get a completely empty window when you try to load the 11.1068 - script. In this case, it's likely that your access 11.1069 - permissions are <emphasis>too permissive</emphasis>. Apache's 11.1070 - <literal>suexec</literal> subsystem won't execute a script 11.1071 - that's group- or world-writable, for example.</para> 11.1072 - 11.1073 - <para id="x_4cb">Your web server may be configured to disallow execution 11.1074 - of CGI programs in your per-user web directory. Here's 11.1075 - Apache's default per-user configuration from my Fedora 11.1076 - system.</para> 11.1077 - 11.1078 - &ch06-apache-config.lst; 11.1079 - 11.1080 - <para id="x_4cc">If you find a similar-looking 11.1081 - <literal>Directory</literal> group in your Apache 11.1082 - configuration, the directive to look at inside it is 11.1083 - <literal>Options</literal>. Add <literal>ExecCGI</literal> 11.1084 - to the end of this list if it's missing, and restart the web 11.1085 - server.</para> 11.1086 - 11.1087 - <para id="x_4cd">If you find that Apache serves you the text of the CGI 11.1088 - script instead of executing it, you may need to either 11.1089 - uncomment (if already present) or add a directive like 11.1090 - this.</para> 11.1091 - <programlisting>AddHandler cgi-script .cgi</programlisting> 11.1092 - 11.1093 - <para id="x_4ce">The next possibility is that you might be served with a 11.1094 - colourful Python backtrace claiming that it can't import a 11.1095 - <literal>mercurial</literal>-related module. This is 11.1096 - actually progress! The server is now capable of executing 11.1097 - your CGI script. This error is only likely to occur if 11.1098 - you're running a private installation of Mercurial, instead 11.1099 - of a system-wide version. Remember that the web server runs 11.1100 - the CGI program without any of the environment variables 11.1101 - that you take for granted in an interactive session. If 11.1102 - this error happens to you, edit your copy of <filename 11.1103 - role="special">hgweb.cgi</filename> and follow the 11.1104 - directions inside it to correctly set your 11.1105 - <envar>PYTHONPATH</envar> environment variable.</para> 11.1106 - 11.1107 - <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be 11.1108 - served with another colourful Python backtrace: this one 11.1109 - will complain that it can't find <filename 11.1110 - class="directory">/path/to/repository</filename>. Edit 11.1111 - your <filename role="special">hgweb.cgi</filename> script 11.1112 - and replace the <filename 11.1113 - class="directory">/path/to/repository</filename> string 11.1114 - with the complete path to the repository you want to serve 11.1115 - up.</para> 11.1116 - 11.1117 - <para id="x_4d0">At this point, when you try to reload the page, you 11.1118 - should be presented with a nice HTML view of your 11.1119 - repository's history. Whew!</para> 11.1120 - </sect3> 11.1121 - 11.1122 - <sect3> 11.1123 - <title>Configuring lighttpd</title> 11.1124 - 11.1125 - <para id="x_4d1">To be exhaustive in my experiments, I tried configuring 11.1126 - the increasingly popular <literal>lighttpd</literal> web 11.1127 - server to serve the same repository as I described with 11.1128 - Apache above. I had already overcome all of the problems I 11.1129 - outlined with Apache, many of which are not server-specific. 11.1130 - As a result, I was fairly sure that my file and directory 11.1131 - permissions were good, and that my <filename 11.1132 - role="special">hgweb.cgi</filename> script was properly 11.1133 - edited.</para> 11.1134 - 11.1135 - <para id="x_4d2">Once I had Apache running, getting 11.1136 - <literal>lighttpd</literal> to serve the repository was a 11.1137 - snap (in other words, even if you're trying to use 11.1138 - <literal>lighttpd</literal>, you should read the Apache 11.1139 - section). I first had to edit the 11.1140 - <literal>mod_access</literal> section of its config file to 11.1141 - enable <literal>mod_cgi</literal> and 11.1142 - <literal>mod_userdir</literal>, both of which were disabled 11.1143 - by default on my system. I then added a few lines to the 11.1144 - end of the config file, to configure these modules.</para> 11.1145 - <programlisting>userdir.path = "public_html" 11.1146 -cgi.assign = (".cgi" => "" )</programlisting> 11.1147 - <para id="x_4d3">With this done, <literal>lighttpd</literal> ran 11.1148 - immediately for me. If I had configured 11.1149 - <literal>lighttpd</literal> before Apache, I'd almost 11.1150 - certainly have run into many of the same system-level 11.1151 - configuration problems as I did with Apache. However, I 11.1152 - found <literal>lighttpd</literal> to be noticeably easier to 11.1153 - configure than Apache, even though I've used Apache for over 11.1154 - a decade, and this was my first exposure to 11.1155 - <literal>lighttpd</literal>.</para> 11.1156 - </sect3> 11.1157 - </sect2> 11.1158 - 11.1159 - <sect2> 11.1160 - <title>Sharing multiple repositories with one CGI script</title> 11.1161 - 11.1162 - <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script 11.1163 - only lets you publish a single repository, which is an 11.1164 - annoying restriction. If you want to publish more than one 11.1165 - without wracking yourself with multiple copies of the same 11.1166 - script, each with different names, a better choice is to use 11.1167 - the <filename role="special">hgwebdir.cgi</filename> 11.1168 - script.</para> 11.1169 - 11.1170 - <para id="x_4d5">The procedure to configure <filename 11.1171 - role="special">hgwebdir.cgi</filename> is only a little more 11.1172 - involved than for <filename 11.1173 - role="special">hgweb.cgi</filename>. First, you must obtain 11.1174 - a copy of the script. If you don't have one handy, you can 11.1175 - download a copy from the master Mercurial repository at <ulink 11.1176 - url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.</para> 11.1177 - 11.1178 - <para id="x_4d6">You'll need to copy this script into your <filename 11.1179 - class="directory">public_html</filename> directory, and 11.1180 - ensure that it's executable.</para> 11.1181 - 11.1182 - <programlisting>cp .../hgwebdir.cgi ~/public_html 11.1183 -chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting> 11.1184 - 11.1185 - <para id="x_4d7">With basic configuration out of the way, try to 11.1186 - visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal> 11.1187 - in your browser. It should 11.1188 - display an empty list of repositories. If you get a blank 11.1189 - window or error message, try walking through the list of 11.1190 - potential problems in <xref 11.1191 - linkend="sec:collab:wtf"/>.</para> 11.1192 - 11.1193 - <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename> 11.1194 - script relies on an external configuration file. By default, 11.1195 - it searches for a file named <filename 11.1196 - role="special">hgweb.config</filename> in the same directory 11.1197 - as itself. You'll need to create this file, and make it 11.1198 - world-readable. The format of the file is similar to a 11.1199 - Windows <quote>ini</quote> file, as understood by Python's 11.1200 - <literal>ConfigParser</literal> 11.1201 - <citation>web:configparser</citation> module.</para> 11.1202 - 11.1203 - <para id="x_4d9">The easiest way to configure <filename 11.1204 - role="special">hgwebdir.cgi</filename> is with a section 11.1205 - named <literal>collections</literal>. This will automatically 11.1206 - publish <emphasis>every</emphasis> repository under the 11.1207 - directories you name. The section should look like 11.1208 - this:</para> 11.1209 - <programlisting>[collections] 11.1210 -/my/root = /my/root</programlisting> 11.1211 - <para id="x_4da">Mercurial interprets this by looking at the directory name 11.1212 - on the <emphasis>right</emphasis> hand side of the 11.1213 - <quote><literal>=</literal></quote> sign; finding repositories 11.1214 - in that directory hierarchy; and using the text on the 11.1215 - <emphasis>left</emphasis> to strip off matching text from the 11.1216 - names it will actually list in the web interface. The 11.1217 - remaining component of a path after this stripping has 11.1218 - occurred is called a <quote>virtual path</quote>.</para> 11.1219 - 11.1220 - <para id="x_4db">Given the example above, if we have a 11.1221 - repository whose local path is <filename 11.1222 - class="directory">/my/root/this/repo</filename>, the CGI 11.1223 - script will strip the leading <filename 11.1224 - class="directory">/my/root</filename> from the name, and 11.1225 - publish the repository with a virtual path of <filename 11.1226 - class="directory">this/repo</filename>. If the base URL for 11.1227 - our CGI script is 11.1228 - <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the 11.1229 - complete URL for that repository will be 11.1230 - <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para> 11.1231 - 11.1232 - <para id="x_4dc">If we replace <filename 11.1233 - class="directory">/my/root</filename> on the left hand side 11.1234 - of this example with <filename 11.1235 - class="directory">/my</filename>, then <filename 11.1236 - role="special">hgwebdir.cgi</filename> will only strip off 11.1237 - <filename class="directory">/my</filename> from the repository 11.1238 - name, and will give us a virtual path of <filename 11.1239 - class="directory">root/this/repo</filename> instead of 11.1240 - <filename class="directory">this/repo</filename>.</para> 11.1241 - 11.1242 - <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename> 11.1243 - script will recursively search each directory listed in the 11.1244 - <literal>collections</literal> section of its configuration 11.1245 - file, but it will <literal>not</literal> recurse into the 11.1246 - repositories it finds.</para> 11.1247 - 11.1248 - <para id="x_4de">The <literal>collections</literal> mechanism makes it easy 11.1249 - to publish many repositories in a <quote>fire and 11.1250 - forget</quote> manner. You only need to set up the CGI 11.1251 - script and configuration file one time. Afterwards, you can 11.1252 - publish or unpublish a repository at any time by simply moving 11.1253 - it into, or out of, the directory hierarchy in which you've 11.1254 - configured <filename role="special">hgwebdir.cgi</filename> to 11.1255 - look.</para> 11.1256 - 11.1257 - <sect3> 11.1258 - <title>Explicitly specifying which repositories to 11.1259 - publish</title> 11.1260 - 11.1261 - <para id="x_4df">In addition to the <literal>collections</literal> 11.1262 - mechanism, the <filename 11.1263 - role="special">hgwebdir.cgi</filename> script allows you 11.1264 - to publish a specific list of repositories. To do so, 11.1265 - create a <literal>paths</literal> section, with contents of 11.1266 - the following form.</para> 11.1267 - <programlisting>[paths] 11.1268 -repo1 = /my/path/to/some/repo 11.1269 -repo2 = /some/path/to/another</programlisting> 11.1270 - <para id="x_4e0">In this case, the virtual path (the component that will 11.1271 - appear in a URL) is on the left hand side of each 11.1272 - definition, while the path to the repository is on the 11.1273 - right. Notice that there does not need to be any 11.1274 - relationship between the virtual path you choose and the 11.1275 - location of a repository in your filesystem.</para> 11.1276 - 11.1277 - <para id="x_4e1">If you wish, you can use both the 11.1278 - <literal>collections</literal> and <literal>paths</literal> 11.1279 - mechanisms simultaneously in a single configuration 11.1280 - file.</para> 11.1281 - 11.1282 - <note> 11.1283 - <title>Beware duplicate virtual paths</title> 11.1284 - 11.1285 - <para id="x_4e2"> If several repositories have the same 11.1286 - virtual path, <filename 11.1287 - role="special">hgwebdir.cgi</filename> will not report 11.1288 - an error. Instead, it will behave unpredictably.</para> 11.1289 - </note> 11.1290 - </sect3> 11.1291 - </sect2> 11.1292 - 11.1293 - <sect2> 11.1294 - <title>Downloading source archives</title> 11.1295 - 11.1296 - <para id="x_4e3">Mercurial's web interface lets users download an archive 11.1297 - of any revision. This archive will contain a snapshot of the 11.1298 - working directory as of that revision, but it will not contain 11.1299 - a copy of the repository data.</para> 11.1300 - 11.1301 - <para id="x_4e4">By default, this feature is not enabled. To enable it, 11.1302 - you'll need to add an <envar 11.1303 - role="rc-item-web">allow_archive</envar> item to the 11.1304 - <literal role="rc-web">web</literal> section of your <filename 11.1305 - role="special">~/.hgrc</filename>; see below for details.</para> 11.1306 - </sect2> 11.1307 - <sect2> 11.1308 - <title>Web configuration options</title> 11.1309 - 11.1310 - <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg 11.1311 - serve</command> command, and the <filename 11.1312 - role="special">hgweb.cgi</filename> and <filename 11.1313 - role="special">hgwebdir.cgi</filename> scripts) have a 11.1314 - number of configuration options that you can set. These 11.1315 - belong in a section named <literal 11.1316 - role="rc-web">web</literal>.</para> 11.1317 - <itemizedlist> 11.1318 - <listitem><para id="x_4e6"><envar 11.1319 - role="rc-item-web">allow_archive</envar>: Determines 11.1320 - which (if any) archive download mechanisms Mercurial 11.1321 - supports. If you enable this feature, users of the web 11.1322 - interface will be able to download an archive of whatever 11.1323 - revision of a repository they are viewing. To enable the 11.1324 - archive feature, this item must take the form of a 11.1325 - sequence of words drawn from the list below.</para> 11.1326 - <itemizedlist> 11.1327 - <listitem><para id="x_4e7"><literal>bz2</literal>: A 11.1328 - <command>tar</command> archive, compressed using 11.1329 - <literal>bzip2</literal> compression. This has the 11.1330 - best compression ratio, but uses the most CPU time on 11.1331 - the server.</para> 11.1332 - </listitem> 11.1333 - <listitem><para id="x_4e8"><literal>gz</literal>: A 11.1334 - <command>tar</command> archive, compressed using 11.1335 - <literal>gzip</literal> compression.</para> 11.1336 - </listitem> 11.1337 - <listitem><para id="x_4e9"><literal>zip</literal>: A 11.1338 - <command>zip</command> archive, compressed using LZW 11.1339 - compression. This format has the worst compression 11.1340 - ratio, but is widely used in the Windows world.</para> 11.1341 - </listitem> 11.1342 - </itemizedlist> 11.1343 - <para id="x_4ea"> If you provide an empty list, or don't have an 11.1344 - <envar role="rc-item-web">allow_archive</envar> entry at 11.1345 - all, this feature will be disabled. Here is an example of 11.1346 - how to enable all three supported formats.</para> 11.1347 - <programlisting>[web] 11.1348 -allow_archive = bz2 gz zip</programlisting> 11.1349 - </listitem> 11.1350 - <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>: 11.1351 - Boolean. Determines whether the web interface allows 11.1352 - remote users to <command role="hg-cmd">hg pull</command> 11.1353 - and <command role="hg-cmd">hg clone</command> this 11.1354 - repository over HTTP. If set to <literal>no</literal> or 11.1355 - <literal>false</literal>, only the 11.1356 - <quote>human-oriented</quote> portion of the web interface 11.1357 - is available.</para> 11.1358 - </listitem> 11.1359 - <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>: 11.1360 - String. A free-form (but preferably brief) string 11.1361 - identifying the person or group in charge of the 11.1362 - repository. This often contains the name and email 11.1363 - address of a person or mailing list. It often makes sense 11.1364 - to place this entry in a repository's own <filename 11.1365 - role="special">.hg/hgrc</filename> file, but it can make 11.1366 - sense to use in a global <filename 11.1367 - role="special">~/.hgrc</filename> if every repository 11.1368 - has a single maintainer.</para> 11.1369 - </listitem> 11.1370 - <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>: 11.1371 - Integer. The default maximum number of changesets to 11.1372 - display in a single page of output.</para> 11.1373 - </listitem> 11.1374 - <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>: 11.1375 - Integer. The default maximum number of modified files to 11.1376 - display in a single page of output.</para> 11.1377 - </listitem> 11.1378 - <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>: 11.1379 - Integer. If the web interface displays alternating 11.1380 - <quote>stripes</quote> to make it easier to visually align 11.1381 - rows when you are looking at a table, this number controls 11.1382 - the number of rows in each stripe.</para> 11.1383 - </listitem> 11.1384 - <listitem><para id="x_4f0"><envar 11.1385 - role="rc-item-web">style</envar>: Controls the template 11.1386 - Mercurial uses to display the web interface. Mercurial 11.1387 - ships with several web templates.</para> 11.1388 - <itemizedlist> 11.1389 - <listitem> 11.1390 - <para id="x_6aa"><literal>coal</literal> is monochromatic.</para> 11.1391 - </listitem> 11.1392 - <listitem> 11.1393 - <para id="x_6ab"><literal>gitweb</literal> emulates the visual 11.1394 - style of git's web interface.</para> 11.1395 - </listitem> 11.1396 - <listitem> 11.1397 - <para id="x_6ac"><literal>monoblue</literal> uses solid blues and 11.1398 - greys.</para> 11.1399 - </listitem> 11.1400 - <listitem> 11.1401 - <para id="x_6ad"><literal>paper</literal> is the default.</para> 11.1402 - </listitem> 11.1403 - <listitem> 11.1404 - <para id="x_6ae"><literal>spartan</literal> was the default for a 11.1405 - long time.</para> 11.1406 - </listitem> 11.1407 - </itemizedlist> 11.1408 - <para id="x_6af">You can 11.1409 - also specify a custom template of your own; see 11.1410 - <xref linkend="chap:template"/> for details. Here, you can 11.1411 - see how to enable the <literal>gitweb</literal> 11.1412 - style.</para> 11.1413 - <programlisting>[web] 11.1414 -style = gitweb</programlisting> 11.1415 - </listitem> 11.1416 - <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>: 11.1417 - Path. The directory in which to search for template 11.1418 - files. By default, Mercurial searches in the directory in 11.1419 - which it was installed.</para> 11.1420 - </listitem></itemizedlist> 11.1421 - <para id="x_4f2">If you are using <filename 11.1422 - role="special">hgwebdir.cgi</filename>, you can place a few 11.1423 - configuration items in a <literal role="rc-web">web</literal> 11.1424 - section of the <filename 11.1425 - role="special">hgweb.config</filename> file instead of a 11.1426 - <filename role="special">~/.hgrc</filename> file, for 11.1427 - convenience. These items are <envar 11.1428 - role="rc-item-web">motd</envar> and <envar 11.1429 - role="rc-item-web">style</envar>.</para> 11.1430 - 11.1431 - <sect3> 11.1432 - <title>Options specific to an individual repository</title> 11.1433 - 11.1434 - <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration 11.1435 - items ought to be placed in a repository's local <filename 11.1436 - role="special">.hg/hgrc</filename>, rather than a user's 11.1437 - or global <filename role="special">~/.hgrc</filename>.</para> 11.1438 - <itemizedlist> 11.1439 - <listitem><para id="x_4f4"><envar 11.1440 - role="rc-item-web">description</envar>: String. A 11.1441 - free-form (but preferably brief) string that describes 11.1442 - the contents or purpose of the repository.</para> 11.1443 - </listitem> 11.1444 - <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>: 11.1445 - String. The name to use for the repository in the web 11.1446 - interface. This overrides the default name, which is 11.1447 - the last component of the repository's path.</para> 11.1448 - </listitem></itemizedlist> 11.1449 - </sect3> 11.1450 - 11.1451 - <sect3> 11.1452 - <title>Options specific to the <command role="hg-cmd">hg 11.1453 - serve</command> command</title> 11.1454 - 11.1455 - <para id="x_4f6">Some of the items in the <literal 11.1456 - role="rc-web">web</literal> section of a <filename 11.1457 - role="special">~/.hgrc</filename> file are only for use 11.1458 - with the <command role="hg-cmd">hg serve</command> 11.1459 - command.</para> 11.1460 - <itemizedlist> 11.1461 - <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>: 11.1462 - Path. The name of a file into which to write an access 11.1463 - log. By default, the <command role="hg-cmd">hg 11.1464 - serve</command> command writes this information to 11.1465 - standard output, not to a file. Log entries are written 11.1466 - in the standard <quote>combined</quote> file format used 11.1467 - by almost all web servers.</para> 11.1468 - </listitem> 11.1469 - <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>: 11.1470 - String. The local address on which the server should 11.1471 - listen for incoming connections. By default, the server 11.1472 - listens on all addresses.</para> 11.1473 - </listitem> 11.1474 - <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>: 11.1475 - Path. The name of a file into which to write an error 11.1476 - log. By default, the <command role="hg-cmd">hg 11.1477 - serve</command> command writes this information to 11.1478 - standard error, not to a file.</para> 11.1479 - </listitem> 11.1480 - <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>: 11.1481 - Boolean. Whether to use the IPv6 protocol. By default, 11.1482 - IPv6 is not used.</para> 11.1483 - </listitem> 11.1484 - <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>: 11.1485 - Integer. The TCP port number on which the server should 11.1486 - listen. The default port number used is 8000.</para> 11.1487 - </listitem></itemizedlist> 11.1488 - </sect3> 11.1489 - 11.1490 - <sect3> 11.1491 - <title>Choosing the right <filename 11.1492 - role="special">~/.hgrc</filename> file to add <literal 11.1493 - role="rc-web">web</literal> items to</title> 11.1494 - 11.1495 - <para id="x_4fc">It is important to remember that a web server like 11.1496 - Apache or <literal>lighttpd</literal> will run under a user 11.1497 - ID that is different to yours. CGI scripts run by your 11.1498 - server, such as <filename 11.1499 - role="special">hgweb.cgi</filename>, will usually also run 11.1500 - under that user ID.</para> 11.1501 - 11.1502 - <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to 11.1503 - your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that 11.1504 - <filename role="special">~/.hgrc</filename> file. Those 11.1505 - settings will thus only affect the behavior of the <command 11.1506 - role="hg-cmd">hg serve</command> command when you run it. 11.1507 - To cause CGI scripts to see your settings, either create a 11.1508 - <filename role="special">~/.hgrc</filename> file in the 11.1509 - home directory of the user ID that runs your web server, or 11.1510 - add those settings to a system-wide <filename 11.1511 - role="special">hgrc</filename> file.</para> 11.1512 - </sect3> 11.1513 - </sect2> 11.1514 - </sect1> 11.1515 - 11.1516 - <sect1> 11.1517 - <title>System-wide configuration</title> 11.1518 - 11.1519 - <para id="x_6b0">On Unix-like systems shared by multiple users (such as a 11.1520 - server to which people publish changes), it often makes sense to 11.1521 - set up some global default behaviors, such as what theme to use 11.1522 - in web interfaces.</para> 11.1523 - 11.1524 - <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename> 11.1525 - exists, Mercurial will read it at startup time and apply any 11.1526 - configuration settings it finds in that file. It will also look 11.1527 - for files ending in a <literal>.rc</literal> extension in a 11.1528 - directory named <filename>/etc/mercurial/hgrc.d</filename>, and 11.1529 - apply any configuration settings it finds in each of those 11.1530 - files.</para> 11.1531 - 11.1532 - <sect2> 11.1533 - <title>Making Mercurial more trusting</title> 11.1534 - 11.1535 - <para id="x_6b2">One situation in which a global <filename>hgrc</filename> 11.1536 - can be useful is if users are pulling changes owned by other 11.1537 - users. By default, Mercurial will not trust most of the 11.1538 - configuration items in a <filename>.hg/hgrc</filename> file 11.1539 - inside a repository that is owned by a different user. If we 11.1540 - clone or pull changes from such a repository, Mercurial will 11.1541 - print a warning stating that it does not trust their 11.1542 - <filename>.hg/hgrc</filename>.</para> 11.1543 - 11.1544 - <para id="x_6b3">If everyone in a particular Unix group is on the same team 11.1545 - and <emphasis>should</emphasis> trust each other's 11.1546 - configuration settings, or we want to trust particular users, 11.1547 - we can override Mercurial's skeptical defaults by creating a 11.1548 - system-wide <filename>hgrc</filename> file such as the 11.1549 - following:</para> 11.1550 - 11.1551 - <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc 11.1552 -[trusted] 11.1553 -# Trust all entries in any hgrc file owned by the "editors" or 11.1554 -# "www-data" groups. 11.1555 -groups = editors, www-data 11.1556 - 11.1557 -# Trust entries in hgrc files owned by the following users. 11.1558 -users = apache, bobo 11.1559 -</programlisting> 11.1560 - </sect2> 11.1561 - </sect1> 11.1562 -</chapter> 11.1563 - 11.1564 -<!-- 11.1565 -local variables: 11.1566 -sgml-parent-document: ("00book.xml" "book" "chapter") 11.1567 -end: 11.1568 --->
12.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 12.2 +++ b/en/ch05-daily.xml Thu May 07 21:07:35 2009 -0700 12.3 @@ -0,0 +1,840 @@ 12.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 12.5 + 12.6 +<chapter id="chap:daily"> 12.7 + <?dbhtml filename="mercurial-in-daily-use.html"?> 12.8 + <title>Mercurial in daily use</title> 12.9 + 12.10 + <sect1> 12.11 + <title>Telling Mercurial which files to track</title> 12.12 + 12.13 + <para id="x_1a3">Mercurial does not work with files in your repository unless 12.14 + you tell it to manage them. The <command role="hg-cmd">hg 12.15 + status</command> command will tell you which files Mercurial 12.16 + doesn't know about; it uses a 12.17 + <quote><literal>?</literal></quote> to display such 12.18 + files.</para> 12.19 + 12.20 + <para id="x_1a4">To tell Mercurial to track a file, use the <command 12.21 + role="hg-cmd">hg add</command> command. Once you have added a 12.22 + file, the entry in the output of <command role="hg-cmd">hg 12.23 + status</command> for that file changes from 12.24 + <quote><literal>?</literal></quote> to 12.25 + <quote><literal>A</literal></quote>.</para> 12.26 + 12.27 + &interaction.daily.files.add; 12.28 + 12.29 + <para id="x_1a5">After you run a <command role="hg-cmd">hg commit</command>, 12.30 + the files that you added before the commit will no longer be 12.31 + listed in the output of <command role="hg-cmd">hg 12.32 + status</command>. The reason for this is that by default, <command 12.33 + role="hg-cmd">hg status</command> only tells you about 12.34 + <quote>interesting</quote> files&emdash;those that you have (for 12.35 + example) modified, removed, or renamed. If you have a repository 12.36 + that contains thousands of files, you will rarely want to know 12.37 + about files that Mercurial is tracking, but that have not 12.38 + changed. (You can still get this information; we'll return to 12.39 + this later.)</para> 12.40 + 12.41 + <para id="x_1a6">Once you add a file, Mercurial doesn't do anything with it 12.42 + immediately. Instead, it will take a snapshot of the file's 12.43 + state the next time you perform a commit. It will then continue 12.44 + to track the changes you make to the file every time you commit, 12.45 + until you remove the file.</para> 12.46 + 12.47 + <sect2> 12.48 + <title>Explicit versus implicit file naming</title> 12.49 + 12.50 + <para id="x_1a7">A useful behavior that Mercurial has is that if you pass 12.51 + the name of a directory to a command, every Mercurial command 12.52 + will treat this as <quote>I want to operate on every file in 12.53 + this directory and its subdirectories</quote>.</para> 12.54 + 12.55 + &interaction.daily.files.add-dir; 12.56 + 12.57 + <para id="x_1a8">Notice in this example that Mercurial printed 12.58 + the names of the files it added, whereas it didn't do so when 12.59 + we added the file named <filename>myfile.txt</filename> in the 12.60 + earlier example.</para> 12.61 + 12.62 + <para id="x_1a9">What's going on is that in the former case, we explicitly 12.63 + named the file to add on the command line. The assumption 12.64 + that Mercurial makes in such cases is that we know what we 12.65 + are doing, and it doesn't print any output.</para> 12.66 + 12.67 + <para id="x_1aa">However, when we <emphasis>imply</emphasis> the names of 12.68 + files by giving the name of a directory, Mercurial takes the 12.69 + extra step of printing the name of each file that it does 12.70 + something with. This makes it more clear what is happening, 12.71 + and reduces the likelihood of a silent and nasty surprise. 12.72 + This behavior is common to most Mercurial commands.</para> 12.73 + </sect2> 12.74 + 12.75 + <sect2> 12.76 + <title>Mercurial tracks files, not directories</title> 12.77 + 12.78 + <para id="x_1ab">Mercurial does not track directory information. Instead, 12.79 + it tracks the path to a file. Before creating a file, it 12.80 + first creates any missing directory components of the path. 12.81 + After it deletes a file, it then deletes any empty directories 12.82 + that were in the deleted file's path. This sounds like a 12.83 + trivial distinction, but it has one minor practical 12.84 + consequence: it is not possible to represent a completely 12.85 + empty directory in Mercurial.</para> 12.86 + 12.87 + <para id="x_1ac">Empty directories are rarely useful, and there are 12.88 + unintrusive workarounds that you can use to achieve an 12.89 + appropriate effect. The developers of Mercurial thus felt 12.90 + that the complexity that would be required to manage empty 12.91 + directories was not worth the limited benefit this feature 12.92 + would bring.</para> 12.93 + 12.94 + <para id="x_1ad">If you need an empty directory in your repository, there 12.95 + are a few ways to achieve this. One is to create a directory, 12.96 + then <command role="hg-cmd">hg add</command> a 12.97 + <quote>hidden</quote> file to that directory. On Unix-like 12.98 + systems, any file name that begins with a period 12.99 + (<quote><literal>.</literal></quote>) is treated as hidden by 12.100 + most commands and GUI tools. This approach is illustrated 12.101 + below.</para> 12.102 + 12.103 +&interaction.daily.files.hidden; 12.104 + 12.105 + <para id="x_1ae">Another way to tackle a need for an empty directory is to 12.106 + simply create one in your automated build scripts before they 12.107 + will need it.</para> 12.108 + </sect2> 12.109 + </sect1> 12.110 + 12.111 + <sect1> 12.112 + <title>How to stop tracking a file</title> 12.113 + 12.114 + <para id="x_1af">Once you decide that a file no longer belongs in 12.115 + your repository, use the <command role="hg-cmd">hg 12.116 + remove</command> command. This deletes the file, and tells 12.117 + Mercurial to stop tracking it (which will occur at the next 12.118 + commit). A removed file is represented in the output of 12.119 + <command role="hg-cmd">hg status</command> with a 12.120 + <quote><literal>R</literal></quote>.</para> 12.121 + 12.122 + &interaction.daily.files.remove; 12.123 + 12.124 + <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file, 12.125 + Mercurial will no longer track changes to that file, even if you 12.126 + recreate a file with the same name in your working directory. 12.127 + If you do recreate a file with the same name and want Mercurial 12.128 + to track the new file, simply <command role="hg-cmd">hg 12.129 + add</command> it. Mercurial will know that the newly added 12.130 + file is not related to the old file of the same name.</para> 12.131 + 12.132 + <sect2> 12.133 + <title>Removing a file does not affect its history</title> 12.134 + 12.135 + <para id="x_1b1">It is important to understand that removing a file has 12.136 + only two effects.</para> 12.137 + <itemizedlist> 12.138 + <listitem><para id="x_1b2">It removes the current version of the file 12.139 + from the working directory.</para> 12.140 + </listitem> 12.141 + <listitem><para id="x_1b3">It stops Mercurial from tracking changes to 12.142 + the file, from the time of the next commit.</para> 12.143 + </listitem></itemizedlist> 12.144 + <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way 12.145 + alter the <emphasis>history</emphasis> of the file.</para> 12.146 + 12.147 + <para id="x_1b5">If you update the working directory to a 12.148 + changeset that was committed when it was still tracking a file 12.149 + that you later removed, the file will reappear in the working 12.150 + directory, with the contents it had when you committed that 12.151 + changeset. If you then update the working directory to a 12.152 + later changeset, in which the file had been removed, Mercurial 12.153 + will once again remove the file from the working 12.154 + directory.</para> 12.155 + </sect2> 12.156 + 12.157 + <sect2> 12.158 + <title>Missing files</title> 12.159 + 12.160 + <para id="x_1b6">Mercurial considers a file that you have deleted, but not 12.161 + used <command role="hg-cmd">hg remove</command> to delete, to 12.162 + be <emphasis>missing</emphasis>. A missing file is 12.163 + represented with <quote><literal>!</literal></quote> in the 12.164 + output of <command role="hg-cmd">hg status</command>. 12.165 + Mercurial commands will not generally do anything with missing 12.166 + files.</para> 12.167 + 12.168 + &interaction.daily.files.missing; 12.169 + 12.170 + <para id="x_1b7">If your repository contains a file that <command 12.171 + role="hg-cmd">hg status</command> reports as missing, and 12.172 + you want the file to stay gone, you can run <command 12.173 + role="hg-cmd">hg remove <option 12.174 + role="hg-opt-remove">--after</option></command> at any 12.175 + time later on, to tell Mercurial that you really did mean to 12.176 + remove the file.</para> 12.177 + 12.178 + &interaction.daily.files.remove-after; 12.179 + 12.180 + <para id="x_1b8">On the other hand, if you deleted the missing file by 12.181 + accident, give <command role="hg-cmd">hg revert</command> the 12.182 + name of the file to recover. It will reappear, in unmodified 12.183 + form.</para> 12.184 + 12.185 + &interaction.daily.files.recover-missing; 12.186 + </sect2> 12.187 + 12.188 + <sect2> 12.189 + <title>Aside: why tell Mercurial explicitly to remove a 12.190 + file?</title> 12.191 + 12.192 + <para id="x_1b9">You might wonder why Mercurial requires you to explicitly 12.193 + tell it that you are deleting a file. Early during the 12.194 + development of Mercurial, it let you delete a file however you 12.195 + pleased; Mercurial would notice the absence of the file 12.196 + automatically when you next ran a <command role="hg-cmd">hg 12.197 + commit</command>, and stop tracking the file. In practice, 12.198 + this made it too easy to accidentally remove a file without 12.199 + noticing.</para> 12.200 + </sect2> 12.201 + 12.202 + <sect2> 12.203 + <title>Useful shorthand&emdash;adding and removing files in one 12.204 + step</title> 12.205 + 12.206 + <para id="x_1ba">Mercurial offers a combination command, <command 12.207 + role="hg-cmd">hg addremove</command>, that adds untracked 12.208 + files and marks missing files as removed.</para> 12.209 + 12.210 + &interaction.daily.files.addremove; 12.211 + 12.212 + <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command 12.213 + also provides a <option role="hg-opt-commit">-A</option> 12.214 + option that performs this same add-and-remove, immediately 12.215 + followed by a commit.</para> 12.216 + 12.217 + &interaction.daily.files.commit-addremove; 12.218 + </sect2> 12.219 + </sect1> 12.220 + 12.221 + <sect1 id="chap:daily.copy"> 12.222 + <title>Copying files</title> 12.223 + 12.224 + <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg 12.225 + copy</command> command that lets you make a new copy of a 12.226 + file. When you copy a file using this command, Mercurial makes 12.227 + a record of the fact that the new file is a copy of the original 12.228 + file. It treats these copied files specially when you merge 12.229 + your work with someone else's.</para> 12.230 + 12.231 + <sect2> 12.232 + <title>The results of copying during a merge</title> 12.233 + 12.234 + <para id="x_1bd">What happens during a merge is that changes 12.235 + <quote>follow</quote> a copy. To best illustrate what this 12.236 + means, let's create an example. We'll start with the usual 12.237 + tiny repository that contains a single file.</para> 12.238 + 12.239 + &interaction.daily.copy.init; 12.240 + 12.241 + <para id="x_1be">We need to do some work in 12.242 + parallel, so that we'll have something to merge. So let's 12.243 + clone our repository.</para> 12.244 + 12.245 + &interaction.daily.copy.clone; 12.246 + 12.247 + <para id="x_1bf">Back in our initial repository, let's use the <command 12.248 + role="hg-cmd">hg copy</command> command to make a copy of 12.249 + the first file we created.</para> 12.250 + 12.251 + &interaction.daily.copy.copy; 12.252 + 12.253 + <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg 12.254 + status</command> command afterwards, the copied file looks 12.255 + just like a normal added file.</para> 12.256 + 12.257 + &interaction.daily.copy.status; 12.258 + 12.259 + <para id="x_1c1">But if we pass the <option 12.260 + role="hg-opt-status">-C</option> option to <command 12.261 + role="hg-cmd">hg status</command>, it prints another line of 12.262 + output: this is the file that our newly-added file was copied 12.263 + <emphasis>from</emphasis>.</para> 12.264 + 12.265 + &interaction.daily.copy.status-copy; 12.266 + 12.267 + <para id="x_1c2">Now, back in the repository we cloned, let's make a change 12.268 + in parallel. We'll add a line of content to the original file 12.269 + that we created.</para> 12.270 + 12.271 + &interaction.daily.copy.other; 12.272 + 12.273 + <para id="x_1c3">Now we have a modified <filename>file</filename> in this 12.274 + repository. When we pull the changes from the first 12.275 + repository, and merge the two heads, Mercurial will propagate 12.276 + the changes that we made locally to <filename>file</filename> 12.277 + into its copy, <filename>new-file</filename>.</para> 12.278 + 12.279 + &interaction.daily.copy.merge; 12.280 + </sect2> 12.281 + 12.282 + <sect2 id="sec:daily:why-copy"> 12.283 + <title>Why should changes follow copies?</title> 12.284 + 12.285 + <para id="x_1c4">This behavior&emdash;of changes to a file 12.286 + propagating out to copies of the file&emdash;might seem 12.287 + esoteric, but in most cases it's highly desirable.</para> 12.288 + 12.289 + <para id="x_1c5">First of all, remember that this propagation 12.290 + <emphasis>only</emphasis> happens when you merge. So if you 12.291 + <command role="hg-cmd">hg copy</command> a file, and 12.292 + subsequently modify the original file during the normal course 12.293 + of your work, nothing will happen.</para> 12.294 + 12.295 + <para id="x_1c6">The second thing to know is that modifications will only 12.296 + propagate across a copy as long as the changeset that you're 12.297 + merging changes from <emphasis>hasn't yet seen</emphasis> 12.298 + the copy.</para> 12.299 + 12.300 + <para id="x_1c7">The reason that Mercurial does this is as follows. Let's 12.301 + say I make an important bug fix in a source file, and commit 12.302 + my changes. Meanwhile, you've decided to <command 12.303 + role="hg-cmd">hg copy</command> the file in your repository, 12.304 + without knowing about the bug or having seen the fix, and you 12.305 + have started hacking on your copy of the file.</para> 12.306 + 12.307 + <para id="x_1c8">If you pulled and merged my changes, and Mercurial 12.308 + <emphasis>didn't</emphasis> propagate changes across copies, 12.309 + your new source file would now contain the bug, and unless you 12.310 + knew to propagate the bug fix by hand, the bug would 12.311 + <emphasis>remain</emphasis> in your copy of the file.</para> 12.312 + 12.313 + <para id="x_1c9">By automatically propagating the change that fixed the bug 12.314 + from the original file to the copy, Mercurial prevents this 12.315 + class of problem. To my knowledge, Mercurial is the 12.316 + <emphasis>only</emphasis> revision control system that 12.317 + propagates changes across copies like this.</para> 12.318 + 12.319 + <para id="x_1ca">Once your change history has a record that the copy and 12.320 + subsequent merge occurred, there's usually no further need to 12.321 + propagate changes from the original file to the copied file, 12.322 + and that's why Mercurial only propagates changes across copies 12.323 + at the first merge, and not afterwards.</para> 12.324 + </sect2> 12.325 + 12.326 + <sect2> 12.327 + <title>How to make changes <emphasis>not</emphasis> follow a 12.328 + copy</title> 12.329 + 12.330 + <para id="x_1cb">If, for some reason, you decide that this business of 12.331 + automatically propagating changes across copies is not for 12.332 + you, simply use your system's normal file copy command (on 12.333 + Unix-like systems, that's <command>cp</command>) to make a 12.334 + copy of a file, then <command role="hg-cmd">hg add</command> 12.335 + the new copy by hand. Before you do so, though, please do 12.336 + reread <xref linkend="sec:daily:why-copy"/>, and make 12.337 + an informed 12.338 + decision that this behavior is not appropriate to your 12.339 + specific case.</para> 12.340 + 12.341 + </sect2> 12.342 + <sect2> 12.343 + <title>Behavior of the <command role="hg-cmd">hg copy</command> 12.344 + command</title> 12.345 + 12.346 + <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command> 12.347 + command, Mercurial makes a copy of each source file as it 12.348 + currently stands in the working directory. This means that if 12.349 + you make some modifications to a file, then <command 12.350 + role="hg-cmd">hg copy</command> it without first having 12.351 + committed those changes, the new copy will also contain the 12.352 + modifications you have made up until that point. (I find this 12.353 + behavior a little counterintuitive, which is why I mention it 12.354 + here.)</para> 12.355 + 12.356 + <para id="x_1cd">The <command role="hg-cmd">hg copy</command> 12.357 + command acts similarly to the Unix <command>cp</command> 12.358 + command (you can use the <command role="hg-cmd">hg 12.359 + cp</command> alias if you prefer). We must supply two or 12.360 + more arguments, of which the last is treated as the 12.361 + <emphasis>destination</emphasis>, and all others are 12.362 + <emphasis>sources</emphasis>.</para> 12.363 + 12.364 + <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a 12.365 + single file as the source, and the destination does not exist, 12.366 + it creates a new file with that name.</para> 12.367 + 12.368 + &interaction.daily.copy.simple; 12.369 + 12.370 + <para id="x_1ce">If the destination is a directory, Mercurial copies its 12.371 + sources into that directory.</para> 12.372 + 12.373 + &interaction.daily.copy.dir-dest; 12.374 + 12.375 + <para id="x_1cf">Copying a directory is 12.376 + recursive, and preserves the directory structure of the 12.377 + source.</para> 12.378 + 12.379 + &interaction.daily.copy.dir-src; 12.380 + 12.381 + <para id="x_1d0">If the source and destination are both directories, the 12.382 + source tree is recreated in the destination directory.</para> 12.383 + 12.384 + &interaction.daily.copy.dir-src-dest; 12.385 + 12.386 + <para id="x_1d1">As with the <command role="hg-cmd">hg remove</command> 12.387 + command, if you copy a file manually and then want Mercurial 12.388 + to know that you've copied the file, simply use the <option 12.389 + role="hg-opt-copy">--after</option> option to <command 12.390 + role="hg-cmd">hg copy</command>.</para> 12.391 + 12.392 + &interaction.daily.copy.after; 12.393 + </sect2> 12.394 + </sect1> 12.395 + 12.396 + <sect1> 12.397 + <title>Renaming files</title> 12.398 + 12.399 + <para id="x_1d2">It's rather more common to need to rename a file than to 12.400 + make a copy of it. The reason I discussed the <command 12.401 + role="hg-cmd">hg copy</command> command before talking about 12.402 + renaming files is that Mercurial treats a rename in essentially 12.403 + the same way as a copy. Therefore, knowing what Mercurial does 12.404 + when you copy a file tells you what to expect when you rename a 12.405 + file.</para> 12.406 + 12.407 + <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command> 12.408 + command, Mercurial makes a copy of each source file, then 12.409 + deletes it and marks the file as removed.</para> 12.410 + 12.411 + &interaction.daily.rename.rename; 12.412 + 12.413 + <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows 12.414 + the newly copied file as added, and the copied-from file as 12.415 + removed.</para> 12.416 + 12.417 + &interaction.daily.rename.status; 12.418 + 12.419 + <para id="x_1d5">As with the results of a <command role="hg-cmd">hg 12.420 + copy</command>, we must use the <option 12.421 + role="hg-opt-status">-C</option> option to <command 12.422 + role="hg-cmd">hg status</command> to see that the added file 12.423 + is really being tracked by Mercurial as a copy of the original, 12.424 + now removed, file.</para> 12.425 + 12.426 + &interaction.daily.rename.status-copy; 12.427 + 12.428 + <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and 12.429 + <command role="hg-cmd">hg copy</command>, you can tell Mercurial 12.430 + about a rename after the fact using the <option 12.431 + role="hg-opt-rename">--after</option> option. In most other 12.432 + respects, the behavior of the <command role="hg-cmd">hg 12.433 + rename</command> command, and the options it accepts, are 12.434 + similar to the <command role="hg-cmd">hg copy</command> 12.435 + command.</para> 12.436 + 12.437 + <para id="x_686">If you're familiar with the Unix command line, you'll be 12.438 + glad to know that <command role="hg-cmd">hg rename</command> 12.439 + command can be invoked as <command role="hg-cmd">hg 12.440 + mv</command>.</para> 12.441 + 12.442 + <sect2> 12.443 + <title>Renaming files and merging changes</title> 12.444 + 12.445 + <para id="x_1d7">Since Mercurial's rename is implemented as 12.446 + copy-and-remove, the same propagation of changes happens when 12.447 + you merge after a rename as after a copy.</para> 12.448 + 12.449 + <para id="x_1d8">If I modify a file, and you rename it to a new name, and 12.450 + then we merge our respective changes, my modifications to the 12.451 + file under its original name will be propagated into the file 12.452 + under its new name. (This is something you might expect to 12.453 + <quote>simply work,</quote> but not all revision control 12.454 + systems actually do this.)</para> 12.455 + 12.456 + <para id="x_1d9">Whereas having changes follow a copy is a feature where 12.457 + you can perhaps nod and say <quote>yes, that might be 12.458 + useful,</quote> it should be clear that having them follow a 12.459 + rename is definitely important. Without this facility, it 12.460 + would simply be too easy for changes to become orphaned when 12.461 + files are renamed.</para> 12.462 + </sect2> 12.463 + 12.464 + <sect2> 12.465 + <title>Divergent renames and merging</title> 12.466 + 12.467 + <para id="x_1da">The case of diverging names occurs when two developers 12.468 + start with a file&emdash;let's call it 12.469 + <filename>foo</filename>&emdash;in their respective 12.470 + repositories.</para> 12.471 + 12.472 + &interaction.rename.divergent.clone; 12.473 + 12.474 + <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para> 12.475 + 12.476 + &interaction.rename.divergent.rename.anne; 12.477 + 12.478 + <para id="x_1dc">Meanwhile, Bob renames it to 12.479 + <filename>quux</filename>. (Remember that <command 12.480 + role="hg-cmd">hg mv</command> is an alias for <command 12.481 + role="hg-cmd">hg rename</command>.)</para> 12.482 + 12.483 + &interaction.rename.divergent.rename.bob; 12.484 + 12.485 + <para id="x_1dd">I like to think of this as a conflict because each 12.486 + developer has expressed different intentions about what the 12.487 + file ought to be named.</para> 12.488 + 12.489 + <para id="x_1de">What do you think should happen when they merge their 12.490 + work? Mercurial's actual behavior is that it always preserves 12.491 + <emphasis>both</emphasis> names when it merges changesets that 12.492 + contain divergent renames.</para> 12.493 + 12.494 + &interaction.rename.divergent.merge; 12.495 + 12.496 + <para id="x_1df">Notice that while Mercurial warns about the divergent 12.497 + renames, it leaves it up to you to do something about the 12.498 + divergence after the merge.</para> 12.499 + </sect2> 12.500 + 12.501 + <sect2> 12.502 + <title>Convergent renames and merging</title> 12.503 + 12.504 + <para id="x_1e0">Another kind of rename conflict occurs when two people 12.505 + choose to rename different <emphasis>source</emphasis> files 12.506 + to the same <emphasis>destination</emphasis>. In this case, 12.507 + Mercurial runs its normal merge machinery, and lets you guide 12.508 + it to a suitable resolution.</para> 12.509 + </sect2> 12.510 + 12.511 + <sect2> 12.512 + <title>Other name-related corner cases</title> 12.513 + 12.514 + <para id="x_1e1">Mercurial has a longstanding bug in which it fails to 12.515 + handle a merge where one side has a file with a given name, 12.516 + while another has a directory with the same name. This is 12.517 + documented as <ulink role="hg-bug" 12.518 + url="http://www.selenic.com/mercurial/bts/issue29">issue 12.519 + 29</ulink>.</para> 12.520 + 12.521 + &interaction.issue29.go; 12.522 + 12.523 + </sect2> 12.524 + </sect1> 12.525 + 12.526 + <sect1> 12.527 + <title>Recovering from mistakes</title> 12.528 + 12.529 + <para id="x_1e2">Mercurial has some useful commands that will help you to 12.530 + recover from some common mistakes.</para> 12.531 + 12.532 + <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets 12.533 + you undo changes that you have made to your working directory. 12.534 + For example, if you <command role="hg-cmd">hg add</command> a 12.535 + file by accident, just run <command role="hg-cmd">hg 12.536 + revert</command> with the name of the file you added, and 12.537 + while the file won't be touched in any way, it won't be tracked 12.538 + for adding by Mercurial any longer, either. You can also use 12.539 + <command role="hg-cmd">hg revert</command> to get rid of 12.540 + erroneous changes to a file.</para> 12.541 + 12.542 + <para id="x_1e4">It is helpful to remember that the <command 12.543 + role="hg-cmd">hg revert</command> command is useful for 12.544 + changes that you have not yet committed. Once you've committed 12.545 + a change, if you decide it was a mistake, you can still do 12.546 + something about it, though your options may be more 12.547 + limited.</para> 12.548 + 12.549 + <para id="x_1e5">For more information about the <command 12.550 + role="hg-cmd">hg revert</command> command, and details about 12.551 + how to deal with changes you have already committed, see <xref 12.552 + linkend="chap:undo"/>.</para> 12.553 + </sect1> 12.554 + 12.555 + <sect1> 12.556 + <title>Dealing with tricky merges</title> 12.557 + 12.558 + <para id="x_687">In a complicated or large project, it's not unusual for a 12.559 + merge of two changesets to result in some headaches. Suppose 12.560 + there's a big source file that's been extensively edited by each 12.561 + side of a merge: this is almost inevitably going to result in 12.562 + conflicts, some of which can take a few tries to sort 12.563 + out.</para> 12.564 + 12.565 + <para id="x_688">Let's develop a simple case of this and see how to deal with 12.566 + it. We'll start off with a repository containing one file, and 12.567 + clone it twice.</para> 12.568 + 12.569 + &interaction.ch04-resolve.init; 12.570 + 12.571 + <para id="x_689">In one clone, we'll modify the file in one way.</para> 12.572 + 12.573 + &interaction.ch04-resolve.left; 12.574 + 12.575 + <para id="x_68a">In another, we'll modify the file differently.</para> 12.576 + 12.577 + &interaction.ch04-resolve.right; 12.578 + 12.579 + <para id="x_68b">Next, we'll pull each set of changes into our original 12.580 + repo.</para> 12.581 + 12.582 + &interaction.ch04-resolve.pull; 12.583 + 12.584 + <para id="x_68c">We expect our repository to now contain two heads.</para> 12.585 + 12.586 + &interaction.ch04-resolve.heads; 12.587 + 12.588 + <para id="x_68d">Normally, if we run <command role="hg-cmd">hg 12.589 + merge</command> at this point, it will drop us into a GUI that 12.590 + will let us manually resolve the conflicting edits to 12.591 + <filename>myfile.txt</filename>. However, to simplify things 12.592 + for presentation here, we'd like the merge to fail immediately 12.593 + instead. Here's one way we can do so.</para> 12.594 + 12.595 + &interaction.ch04-resolve.export; 12.596 + 12.597 + <para id="x_68e">We've told Mercurial's merge machinery to run the command 12.598 + <command>false</command> (which, as we desire, fails 12.599 + immediately) if it detects a merge that it can't sort out 12.600 + automatically.</para> 12.601 + 12.602 + <para id="x_68f">If we now fire up <command role="hg-cmd">hg 12.603 + merge</command>, it should grind to a halt and report a 12.604 + failure.</para> 12.605 + 12.606 + &interaction.ch04-resolve.merge; 12.607 + 12.608 + <para id="x_690">Even if we don't notice that the merge failed, Mercurial 12.609 + will prevent us from accidentally committing the result of a 12.610 + failed merge.</para> 12.611 + 12.612 + &interaction.ch04-resolve.cifail; 12.613 + 12.614 + <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in 12.615 + this case, it suggests that we use the unfamiliar <command 12.616 + role="hg-cmd">hg resolve</command> command. As usual, 12.617 + <command role="hg-cmd">hg help resolve</command> will print a 12.618 + helpful synopsis.</para> 12.619 + 12.620 + <sect2> 12.621 + <title>File resolution states</title> 12.622 + 12.623 + <para id="x_692">When a merge occurs, most files will usually remain 12.624 + unmodified. For each file where Mercurial has to do 12.625 + something, it tracks the state of the file.</para> 12.626 + 12.627 + <itemizedlist> 12.628 + <listitem> 12.629 + <para id="x_693">A <emphasis>resolved</emphasis> file has been 12.630 + successfully merged, either automatically by Mercurial or 12.631 + manually with human intervention.</para> 12.632 + </listitem> 12.633 + <listitem> 12.634 + <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged 12.635 + successfully, and needs more attention.</para> 12.636 + </listitem> 12.637 + </itemizedlist> 12.638 + 12.639 + <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the 12.640 + unresolved state after a merge, it considers the merge to have 12.641 + failed. Fortunately, we do not need to restart the entire 12.642 + merge from scratch.</para> 12.643 + 12.644 + <para id="x_696">The <option role="hg-opt-resolve">--list</option> or 12.645 + <option role="hg-opt-resolve">-l</option> option to <command 12.646 + role="hg-cmd">hg resolve</command> prints out the state of 12.647 + each merged file.</para> 12.648 + 12.649 + &interaction.ch04-resolve.list; 12.650 + 12.651 + <para id="x_697">In the output from <command role="hg-cmd">hg 12.652 + resolve</command>, a resolved file is marked with 12.653 + <literal>R</literal>, while an unresolved file is marked with 12.654 + <literal>U</literal>. If any files are listed with 12.655 + <literal>U</literal>, we know that an attempt to commit the 12.656 + results of the merge will fail.</para> 12.657 + </sect2> 12.658 + 12.659 + <sect2> 12.660 + <title>Resolving a file merge</title> 12.661 + 12.662 + <para id="x_698">We have several options to move a file from the unresolved 12.663 + into the resolved state. By far the most common is to rerun 12.664 + <command role="hg-cmd">hg resolve</command>. If we pass the 12.665 + names of individual files or directories, it will retry the 12.666 + merges of any unresolved files present in those locations. We 12.667 + can also pass the <option role="hg-opt-resolve">--all</option> 12.668 + or <option role="hg-opt-resolve">-a</option> option, which 12.669 + will retry the merges of <emphasis>all</emphasis> unresolved 12.670 + files.</para> 12.671 + 12.672 + <para id="x_699">Mercurial also lets us modify the resolution state of a 12.673 + file directly. We can manually mark a file as resolved using 12.674 + the <option role="hg-opt-resolve">--mark</option> option, or 12.675 + as unresolved using the <option 12.676 + role="hg-opt-resolve">--unmark</option> option. This allows 12.677 + us to clean up a particularly messy merge by hand, and to keep 12.678 + track of our progress with each file as we go.</para> 12.679 + </sect2> 12.680 + </sect1> 12.681 + 12.682 + <sect1> 12.683 + <title>More useful diffs</title> 12.684 + 12.685 + <para id="x_6c7">The default output of the <command role="hg-cmd">hg 12.686 + diff</command> command is backwards compatible with the 12.687 + regular <command>diff</command> command, but this has some 12.688 + drawbacks.</para> 12.689 + 12.690 + <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg 12.691 + rename</command> to rename a file.</para> 12.692 + 12.693 + &interaction.ch04-diff.rename.basic; 12.694 + 12.695 + <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above 12.696 + obscures the fact that we simply renamed a file. The <command 12.697 + role="hg-cmd">hg diff</command> command accepts an option, 12.698 + <option>--git</option> or <option>-g</option>, to use a newer 12.699 + diff format that displays such information in a more readable 12.700 + form.</para> 12.701 + 12.702 + &interaction.ch04-diff.rename.git; 12.703 + 12.704 + <para id="x_6ca">This option also helps with a case that can otherwise be 12.705 + confusing: a file that appears to be modified according to 12.706 + <command role="hg-cmd">hg status</command>, but for which 12.707 + <command role="hg-cmd">hg diff</command> prints nothing. This 12.708 + situation can arise if we change the file's execute 12.709 + permissions.</para> 12.710 + 12.711 + &interaction.ch04-diff.chmod; 12.712 + 12.713 + <para id="x_6cb">The normal <command>diff</command> command pays no attention 12.714 + to file permissions, which is why <command role="hg-cmd">hg 12.715 + diff</command> prints nothing by default. If we supply it 12.716 + with the <option>-g</option> option, it tells us what really 12.717 + happened.</para> 12.718 + 12.719 + &interaction.ch04-diff.chmod.git; 12.720 + </sect1> 12.721 + 12.722 + <sect1> 12.723 + <title>Which files to manage, and which to avoid</title> 12.724 + 12.725 + <para id="x_6cc">Revision control systems are generally best at managing text 12.726 + files that are written by humans, such as source code, where the 12.727 + files do not change much from one revision to the next. Some 12.728 + centralized revision control systems can also deal tolerably 12.729 + well with binary files, such as bitmap images.</para> 12.730 + 12.731 + <para id="x_6cd">For instance, a game development team will typically manage 12.732 + both its source code and all of its binary assets (e.g. geometry 12.733 + data, textures, map layouts) in a revision control 12.734 + system.</para> 12.735 + 12.736 + <para id="x_6ce">Because it is usually impossible to merge two conflicting 12.737 + modifications to a binary file, centralized systems often 12.738 + provide a file locking mechanism that allow a user to say 12.739 + <quote>I am the only person who can edit this 12.740 + file</quote>.</para> 12.741 + 12.742 + <para id="x_6cf">Compared to a centralized system, a distributed revision 12.743 + control system changes some of the factors that guide decisions 12.744 + over which files to manage and how.</para> 12.745 + 12.746 + <para id="x_6d0">For instance, a distributed revision control system cannot, 12.747 + by its nature, offer a file locking facility. There is thus no 12.748 + built-in mechanism to prevent two people from making conflicting 12.749 + changes to a binary file. If you have a team where several 12.750 + people may be editing binary files frequently, it may not be a 12.751 + good idea to use Mercurial&emdash;or any other distributed 12.752 + revision control system&emdash;to manage those files.</para> 12.753 + 12.754 + <para id="x_6d1">When storing modifications to a file, Mercurial usually 12.755 + saves only the differences between the previous and current 12.756 + versions of the file. For most text files, this is extremely 12.757 + efficient. However, some files (particularly binary files) are 12.758 + laid out in such a way that even a small change to a file's 12.759 + logical content results in many or most of the bytes inside the 12.760 + file changing. For instance, compressed files are particularly 12.761 + susceptible to this. If the differences between each successive 12.762 + version of a file are always large, Mercurial will not be able 12.763 + to store the file's revision history very efficiently. This can 12.764 + affect both local storage needs and the amount of time it takes 12.765 + to clone a repository.</para> 12.766 + 12.767 + <para id="x_6d2">To get an idea of how this could affect you in practice, 12.768 + suppose you want to use Mercurial to manage an OpenOffice 12.769 + document. OpenOffice stores documents on disk as compressed zip 12.770 + files. Edit even a single letter of your document in OpenOffice, 12.771 + and almost every byte in the entire file will change when you 12.772 + save it. Now suppose that file is 2MB in size. Because most of 12.773 + the file changes every time you save, Mercurial will have to 12.774 + store all 2MB of the file every time you commit, even though 12.775 + from your perspective, perhaps only a few words are changing 12.776 + each time. A single frequently-edited file that is not friendly 12.777 + to Mercurial's storage assumptions can easily have an outsized 12.778 + effect on the size of the repository.</para> 12.779 + 12.780 + <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice 12.781 + document you're working on, there is no useful way to merge your 12.782 + work. In fact, there isn't even a good way to tell what the 12.783 + differences are between your respective changes.</para> 12.784 + 12.785 + <para id="x_6d4">There are thus a few clear recommendations about specific 12.786 + kinds of files to be very careful with.</para> 12.787 + 12.788 + <itemizedlist> 12.789 + <listitem> 12.790 + <para id="x_6d5">Files that are very large and incompressible, e.g. ISO 12.791 + CD-ROM images, will by virtue of sheer size make clones over 12.792 + a network very slow.</para> 12.793 + </listitem> 12.794 + <listitem> 12.795 + <para id="x_6d6">Files that change a lot from one revision to the next 12.796 + may be expensive to store if you edit them frequently, and 12.797 + conflicts due to concurrent edits may be difficult to 12.798 + resolve.</para> 12.799 + </listitem> 12.800 + </itemizedlist> 12.801 + </sect1> 12.802 + 12.803 + <sect1> 12.804 + <title>Backups and mirroring</title> 12.805 + 12.806 + <para id="x_6d7">Since Mercurial maintains a complete copy of history in each 12.807 + clone, everyone who uses Mercurial to collaborate on a project 12.808 + can potentially act as a source of backups in the event of a 12.809 + catastrophe. If a central repository becomes unavailable, you 12.810 + can construct a replacement simply by cloning a copy of the 12.811 + repository from one contributor, and pulling any changes they 12.812 + may not have seen from others.</para> 12.813 + 12.814 + <para id="x_6d8">It is simple to use Mercurial to perform off-site backups 12.815 + and remote mirrors. Set up a periodic job (e.g. via the 12.816 + <command>cron</command> command) on a remote server to pull 12.817 + changes from your master repositories every hour. This will 12.818 + only be tricky in the unlikely case that the number of master 12.819 + repositories you maintain changes frequently, in which case 12.820 + you'll need to do a little scripting to refresh the list of 12.821 + repositories to back up.</para> 12.822 + 12.823 + <para id="x_6d9">If you perform traditional backups of your master 12.824 + repositories to tape or disk, and you want to back up a 12.825 + repository named <filename>myrepo</filename>, use <command>hg 12.826 + clone -U myrepo myrepo.bak</command> to create a 12.827 + clone of <filename>myrepo</filename> before you start your 12.828 + backups. The <option>-U</option> option doesn't check out a 12.829 + working directory after the clone completes, since that would be 12.830 + superfluous and make the backup take longer.</para> 12.831 + 12.832 + <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead 12.833 + of <filename>myrepo</filename>, you will be guaranteed to have a 12.834 + consistent snapshot of your repository that won't be pushed to 12.835 + by an insomniac developer in mid-backup.</para> 12.836 + </sect1> 12.837 +</chapter> 12.838 + 12.839 +<!-- 12.840 +local variables: 12.841 +sgml-parent-document: ("00book.xml" "book" "chapter") 12.842 +end: 12.843 +-->
13.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 13.2 +++ b/en/ch06-collab.xml Thu May 07 21:07:35 2009 -0700 13.3 @@ -0,0 +1,1565 @@ 13.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 13.5 + 13.6 +<chapter id="cha:collab"> 13.7 + <?dbhtml filename="collaborating-with-other-people.html"?> 13.8 + <title>Collaborating with other people</title> 13.9 + 13.10 + <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose 13.11 + any policy on how people ought to work with each other. However, 13.12 + if you're new to distributed revision control, it helps to have 13.13 + some tools and examples in mind when you're thinking about 13.14 + possible workflow models.</para> 13.15 + 13.16 + <sect1> 13.17 + <title>Mercurial's web interface</title> 13.18 + 13.19 + <para id="x_44b">Mercurial has a powerful web interface that provides several 13.20 + useful capabilities.</para> 13.21 + 13.22 + <para id="x_44c">For interactive use, the web interface lets you browse a 13.23 + single repository or a collection of repositories. You can view 13.24 + the history of a repository, examine each change (comments and 13.25 + diffs), and view the contents of each directory and file. You 13.26 + can even get a view of history that gives a graphical view of 13.27 + the relationships between individual changes and merges.</para> 13.28 + 13.29 + <para id="x_44d">Also for human consumption, the web interface provides 13.30 + Atom and RSS feeds of the changes in a repository. This lets you 13.31 + <quote>subscribe</quote> to a repository using your favorite 13.32 + feed reader, and be automatically notified of activity in that 13.33 + repository as soon as it happens. I find this capability much 13.34 + more convenient than the model of subscribing to a mailing list 13.35 + to which notifications are sent, as it requires no additional 13.36 + configuration on the part of whoever is serving the 13.37 + repository.</para> 13.38 + 13.39 + <para id="x_44e">The web interface also lets remote users clone a repository, 13.40 + pull changes from it, and (when the server is configured to 13.41 + permit it) push changes back to it. Mercurial's HTTP tunneling 13.42 + protocol aggressively compresses data, so that it works 13.43 + efficiently even over low-bandwidth network connections.</para> 13.44 + 13.45 + <para id="x_44f">The easiest way to get started with the web interface is to 13.46 + use your web browser to visit an existing repository, such as 13.47 + the master Mercurial repository at <ulink 13.48 + url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para> 13.49 + 13.50 + <para id="x_450">If you're interested in providing a web interface 13.51 + to your own repositories, there are several good ways to do 13.52 + this.</para> 13.53 + 13.54 + <para id="x_69d">The easiest and fastest way to get started in an informal 13.55 + environment is to use the <command role="hg-cmd">hg 13.56 + serve</command> command, which is best suited to short-term 13.57 + <quote>lightweight</quote> serving. See <xref 13.58 + linkend="sec:collab:serve"/> below for details of how to use 13.59 + this command.</para> 13.60 + 13.61 + <para id="x_69e">For longer-lived repositories that you'd like to 13.62 + have permanently available, there are several public hosting 13.63 + services available. Some are free to open source projects, 13.64 + while others offer paid commercial hosting. An up-to-date list 13.65 + is available at <ulink 13.66 + url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para> 13.67 + 13.68 + <para id="x_6a0">If you would prefer to host your own repositories, Mercurial 13.69 + has built-in support for several popular hosting technologies, 13.70 + most notably CGI (Common Gateway Interface), and WSGI (Web 13.71 + Services Gateway Interface). See <xref 13.72 + linkend="sec:collab:cgi"/> for details of CGI and WSGI 13.73 + configuration.</para> 13.74 + </sect1> 13.75 + 13.76 + <sect1> 13.77 + <title>Collaboration models</title> 13.78 + 13.79 + <para id="x_451">With a suitably flexible tool, making decisions about 13.80 + workflow is much more of a social engineering challenge than a 13.81 + technical one. Mercurial imposes few limitations on how you can 13.82 + structure the flow of work in a project, so it's up to you and 13.83 + your group to set up and live with a model that matches your own 13.84 + particular needs.</para> 13.85 + 13.86 + <sect2> 13.87 + <title>Factors to keep in mind</title> 13.88 + 13.89 + <para id="x_452">The most important aspect of any model that you must keep 13.90 + in mind is how well it matches the needs and capabilities of 13.91 + the people who will be using it. This might seem 13.92 + self-evident; even so, you still can't afford to forget it for 13.93 + a moment.</para> 13.94 + 13.95 + <para id="x_453">I once put together a workflow model that seemed to make 13.96 + perfect sense to me, but that caused a considerable amount of 13.97 + consternation and strife within my development team. In spite 13.98 + of my attempts to explain why we needed a complex set of 13.99 + branches, and how changes ought to flow between them, a few 13.100 + team members revolted. Even though they were smart people, 13.101 + they didn't want to pay attention to the constraints we were 13.102 + operating under, or face the consequences of those constraints 13.103 + in the details of the model that I was advocating.</para> 13.104 + 13.105 + <para id="x_454">Don't sweep foreseeable social or technical problems under 13.106 + the rug. Whatever scheme you put into effect, you should plan 13.107 + for mistakes and problem scenarios. Consider adding automated 13.108 + machinery to prevent, or quickly recover from, trouble that 13.109 + you can anticipate. As an example, if you intend to have a 13.110 + branch with not-for-release changes in it, you'd do well to 13.111 + think early about the possibility that someone might 13.112 + accidentally merge those changes into a release branch. You 13.113 + could avoid this particular problem by writing a hook that 13.114 + prevents changes from being merged from an inappropriate 13.115 + branch.</para> 13.116 + </sect2> 13.117 + 13.118 + <sect2> 13.119 + <title>Informal anarchy</title> 13.120 + 13.121 + <para id="x_455">I wouldn't suggest an <quote>anything goes</quote> 13.122 + approach as something sustainable, but it's a model that's 13.123 + easy to grasp, and it works perfectly well in a few unusual 13.124 + situations.</para> 13.125 + 13.126 + <para id="x_456">As one example, many projects have a loose-knit group of 13.127 + collaborators who rarely physically meet each other. Some 13.128 + groups like to overcome the isolation of working at a distance 13.129 + by organizing occasional <quote>sprints</quote>. In a sprint, 13.130 + a number of people get together in a single location (a 13.131 + company's conference room, a hotel meeting room, that kind of 13.132 + place) and spend several days more or less locked in there, 13.133 + hacking intensely on a handful of projects.</para> 13.134 + 13.135 + <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the 13.136 + <command role="hg-cmd">hg serve</command> command, since 13.137 + <command role="hg-cmd">hg serve</command> does not require any 13.138 + fancy server infrastructure. You can get started with 13.139 + <command role="hg-cmd">hg serve</command> in moments, by 13.140 + reading <xref linkend="sec:collab:serve"/> below. Then simply 13.141 + tell the person next to you that you're running a server, send 13.142 + the URL to them in an instant message, and you immediately 13.143 + have a quick-turnaround way to work together. They can type 13.144 + your URL into their web browser and quickly review your 13.145 + changes; or they can pull a bugfix from you and verify it; or 13.146 + they can clone a branch containing a new feature and try it 13.147 + out.</para> 13.148 + 13.149 + <para id="x_458">The charm, and the problem, with doing things 13.150 + in an ad hoc fashion like this is that only people who know 13.151 + about your changes, and where they are, can see them. Such an 13.152 + informal approach simply doesn't scale beyond a handful 13.153 + people, because each individual needs to know about 13.154 + <emphasis>n</emphasis> different repositories to pull 13.155 + from.</para> 13.156 + </sect2> 13.157 + 13.158 + <sect2> 13.159 + <title>A single central repository</title> 13.160 + 13.161 + <para id="x_459">For smaller projects migrating from a centralised revision 13.162 + control tool, perhaps the easiest way to get started is to 13.163 + have changes flow through a single shared central repository. 13.164 + This is also the most common <quote>building block</quote> for 13.165 + more ambitious workflow schemes.</para> 13.166 + 13.167 + <para id="x_45a">Contributors start by cloning a copy of this repository. 13.168 + They can pull changes from it whenever they need to, and some 13.169 + (perhaps all) developers have permission to push a change back 13.170 + when they're ready for other people to see it.</para> 13.171 + 13.172 + <para id="x_45b">Under this model, it can still often make sense for people 13.173 + to pull changes directly from each other, without going 13.174 + through the central repository. Consider a case in which I 13.175 + have a tentative bug fix, but I am worried that if I were to 13.176 + publish it to the central repository, it might subsequently 13.177 + break everyone else's trees as they pull it. To reduce the 13.178 + potential for damage, I can ask you to clone my repository 13.179 + into a temporary repository of your own and test it. This 13.180 + lets us put off publishing the potentially unsafe change until 13.181 + it has had a little testing.</para> 13.182 + 13.183 + <para id="x_45c">If a team is hosting its own repository in this 13.184 + kind of scenario, people will usually use the 13.185 + <command>ssh</command> protocol to securely push changes to 13.186 + the central repository, as documented in <xref 13.187 + linkend="sec:collab:ssh"/>. It's also usual to publish a 13.188 + read-only copy of the repository over HTTP, as in 13.189 + <xref linkend="sec:collab:cgi"/>. Publishing over HTTP 13.190 + satisfies the needs of people who don't have push access, and 13.191 + those who want to use web browsers to browse the repository's 13.192 + history.</para> 13.193 + </sect2> 13.194 + 13.195 + <sect2> 13.196 + <title>A hosted central repository</title> 13.197 + 13.198 + <para id="x_6a1">A wonderful thing about public hosting services like 13.199 + <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that 13.200 + not only do they handle the fiddly server configuration 13.201 + details, such as user accounts, authentication, and secure 13.202 + wire protocols, they provide additional infrastructure to make 13.203 + this model work well.</para> 13.204 + 13.205 + <para id="x_6a2">For instance, a well-engineered hosting service will let 13.206 + people clone their own copies of a repository with a single 13.207 + click. This lets people work in separate spaces and share 13.208 + their changes when they're ready.</para> 13.209 + 13.210 + <para id="x_6a3">In addition, a good hosting service will let people 13.211 + communicate with each other, for instance to say <quote>there 13.212 + are changes ready for you to review in this 13.213 + tree</quote>.</para> 13.214 + </sect2> 13.215 + 13.216 + <sect2> 13.217 + <title>Working with multiple branches</title> 13.218 + 13.219 + <para id="x_45d">Projects of any significant size naturally tend to make 13.220 + progress on several fronts simultaneously. In the case of 13.221 + software, it's common for a project to go through periodic 13.222 + official releases. A release might then go into 13.223 + <quote>maintenance mode</quote> for a while after its first 13.224 + publication; maintenance releases tend to contain only bug 13.225 + fixes, not new features. In parallel with these maintenance 13.226 + releases, one or more future releases may be under 13.227 + development. People normally use the word 13.228 + <quote>branch</quote> to refer to one of these many slightly 13.229 + different directions in which development is 13.230 + proceeding.</para> 13.231 + 13.232 + <para id="x_45e">Mercurial is particularly well suited to managing a number 13.233 + of simultaneous, but not identical, branches. Each 13.234 + <quote>development direction</quote> can live in its own 13.235 + central repository, and you can merge changes from one to 13.236 + another as the need arises. Because repositories are 13.237 + independent of each other, unstable changes in a development 13.238 + branch will never affect a stable branch unless someone 13.239 + explicitly merges those changes into the stable branch.</para> 13.240 + 13.241 + <para id="x_45f">Here's an example of how this can work in practice. Let's 13.242 + say you have one <quote>main branch</quote> on a central 13.243 + server.</para> 13.244 + 13.245 + &interaction.branching.init; 13.246 + 13.247 + <para id="x_460">People clone it, make changes locally, test them, and push 13.248 + them back.</para> 13.249 + 13.250 + <para id="x_461">Once the main branch reaches a release milestone, you can 13.251 + use the <command role="hg-cmd">hg tag</command> command to 13.252 + give a permanent name to the milestone revision.</para> 13.253 + 13.254 + &interaction.branching.tag; 13.255 + 13.256 + <para id="x_462">Let's say some ongoing 13.257 + development occurs on the main branch.</para> 13.258 + 13.259 + &interaction.branching.main; 13.260 + 13.261 + <para id="x_463">Using the tag that was recorded at the milestone, people 13.262 + who clone that repository at any time in the future can use 13.263 + <command role="hg-cmd">hg update</command> to get a copy of 13.264 + the working directory exactly as it was when that tagged 13.265 + revision was committed.</para> 13.266 + 13.267 + &interaction.branching.update; 13.268 + 13.269 + <para id="x_464">In addition, immediately after the main branch is tagged, 13.270 + we can then clone the main branch on the server to a new 13.271 + <quote>stable</quote> branch, also on the server.</para> 13.272 + 13.273 + &interaction.branching.clone; 13.274 + 13.275 + <para id="x_465">If we need to make a change to the stable 13.276 + branch, we can then clone <emphasis>that</emphasis> 13.277 + repository, make our changes, commit, and push our changes 13.278 + back there.</para> 13.279 + 13.280 + &interaction.branching.stable; 13.281 + 13.282 + <para id="x_466">Because Mercurial repositories are independent, and 13.283 + Mercurial doesn't move changes around automatically, the 13.284 + stable and main branches are <emphasis>isolated</emphasis> 13.285 + from each other. The changes that we made on the main branch 13.286 + don't <quote>leak</quote> to the stable branch, and vice 13.287 + versa.</para> 13.288 + 13.289 + <para id="x_467">We'll often want all of our bugfixes on the stable 13.290 + branch to show up on the main branch, too. Rather than 13.291 + rewrite a bugfix on the main branch, we can simply pull and 13.292 + merge changes from the stable to the main branch, and 13.293 + Mercurial will bring those bugfixes in for us.</para> 13.294 + 13.295 + &interaction.branching.merge; 13.296 + 13.297 + <para id="x_468">The main branch will still contain changes that 13.298 + are not on the stable branch, but it will also contain all of 13.299 + the bugfixes from the stable branch. The stable branch 13.300 + remains unaffected by these changes, since changes are only 13.301 + flowing from the stable to the main branch, and not the other 13.302 + way.</para> 13.303 + </sect2> 13.304 + 13.305 + <sect2> 13.306 + <title>Feature branches</title> 13.307 + 13.308 + <para id="x_469">For larger projects, an effective way to manage change is 13.309 + to break up a team into smaller groups. Each group has a 13.310 + shared branch of its own, cloned from a single 13.311 + <quote>master</quote> branch used by the entire project. 13.312 + People working on an individual branch are typically quite 13.313 + isolated from developments on other branches.</para> 13.314 + 13.315 + <figure id="fig:collab:feature-branches"> 13.316 + <title>Feature branches</title> 13.317 + <mediaobject> 13.318 + <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject> 13.319 + <textobject><phrase>XXX add text</phrase></textobject> 13.320 + </mediaobject> 13.321 + </figure> 13.322 + 13.323 + <para id="x_46b">When a particular feature is deemed to be in suitable 13.324 + shape, someone on that feature team pulls and merges from the 13.325 + master branch into the feature branch, then pushes back up to 13.326 + the master branch.</para> 13.327 + </sect2> 13.328 + 13.329 + <sect2> 13.330 + <title>The release train</title> 13.331 + 13.332 + <para id="x_46c">Some projects are organized on a <quote>train</quote> 13.333 + basis: a release is scheduled to happen every few months, and 13.334 + whatever features are ready when the <quote>train</quote> is 13.335 + ready to leave are allowed in.</para> 13.336 + 13.337 + <para id="x_46d">This model resembles working with feature branches. The 13.338 + difference is that when a feature branch misses a train, 13.339 + someone on the feature team pulls and merges the changes that 13.340 + went out on that train release into the feature branch, and 13.341 + the team continues its work on top of that release so that 13.342 + their feature can make the next release.</para> 13.343 + </sect2> 13.344 + 13.345 + <sect2> 13.346 + <title>The Linux kernel model</title> 13.347 + 13.348 + <para id="x_46e">The development of the Linux kernel has a shallow 13.349 + hierarchical structure, surrounded by a cloud of apparent 13.350 + chaos. Because most Linux developers use 13.351 + <command>git</command>, a distributed revision control tool 13.352 + with capabilities similar to Mercurial, it's useful to 13.353 + describe the way work flows in that environment; if you like 13.354 + the ideas, the approach translates well across tools.</para> 13.355 + 13.356 + <para id="x_46f">At the center of the community sits Linus Torvalds, the 13.357 + creator of Linux. He publishes a single source repository 13.358 + that is considered the <quote>authoritative</quote> current 13.359 + tree by the entire developer community. Anyone can clone 13.360 + Linus's tree, but he is very choosy about whose trees he pulls 13.361 + from.</para> 13.362 + 13.363 + <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>. 13.364 + As a general rule, he pulls whatever changes they publish, in 13.365 + most cases without even reviewing those changes. Some of 13.366 + those lieutenants are generally agreed to be 13.367 + <quote>maintainers</quote>, responsible for specific 13.368 + subsystems within the kernel. If a random kernel hacker wants 13.369 + to make a change to a subsystem that they want to end up in 13.370 + Linus's tree, they must find out who the subsystem's 13.371 + maintainer is, and ask that maintainer to take their change. 13.372 + If the maintainer reviews their changes and agrees to take 13.373 + them, they'll pass them along to Linus in due course.</para> 13.374 + 13.375 + <para id="x_471">Individual lieutenants have their own approaches to 13.376 + reviewing, accepting, and publishing changes; and for deciding 13.377 + when to feed them to Linus. In addition, there are several 13.378 + well known branches that people use for different purposes. 13.379 + For example, a few people maintain <quote>stable</quote> 13.380 + repositories of older versions of the kernel, to which they 13.381 + apply critical fixes as needed. Some maintainers publish 13.382 + multiple trees: one for experimental changes; one for changes 13.383 + that they are about to feed upstream; and so on. Others just 13.384 + publish a single tree.</para> 13.385 + 13.386 + <para id="x_472">This model has two notable features. The first is that 13.387 + it's <quote>pull only</quote>. You have to ask, convince, or 13.388 + beg another developer to take a change from you, because there 13.389 + are almost no trees to which more than one person can push, 13.390 + and there's no way to push changes into a tree that someone 13.391 + else controls.</para> 13.392 + 13.393 + <para id="x_473">The second is that it's based on reputation and acclaim. 13.394 + If you're an unknown, Linus will probably ignore changes from 13.395 + you without even responding. But a subsystem maintainer will 13.396 + probably review them, and will likely take them if they pass 13.397 + their criteria for suitability. The more <quote>good</quote> 13.398 + changes you contribute to a maintainer, the more likely they 13.399 + are to trust your judgment and accept your changes. If you're 13.400 + well-known and maintain a long-lived branch for something 13.401 + Linus hasn't yet accepted, people with similar interests may 13.402 + pull your changes regularly to keep up with your work.</para> 13.403 + 13.404 + <para id="x_474">Reputation and acclaim don't necessarily cross subsystem 13.405 + or <quote>people</quote> boundaries. If you're a respected 13.406 + but specialised storage hacker, and you try to fix a 13.407 + networking bug, that change will receive a level of scrutiny 13.408 + from a network maintainer comparable to a change from a 13.409 + complete stranger.</para> 13.410 + 13.411 + <para id="x_475">To people who come from more orderly project backgrounds, 13.412 + the comparatively chaotic Linux kernel development process 13.413 + often seems completely insane. It's subject to the whims of 13.414 + individuals; people make sweeping changes whenever they deem 13.415 + it appropriate; and the pace of development is astounding. 13.416 + And yet Linux is a highly successful, well-regarded piece of 13.417 + software.</para> 13.418 + </sect2> 13.419 + 13.420 + <sect2> 13.421 + <title>Pull-only versus shared-push collaboration</title> 13.422 + 13.423 + <para id="x_476">A perpetual source of heat in the open source community is 13.424 + whether a development model in which people only ever pull 13.425 + changes from others is <quote>better than</quote> one in which 13.426 + multiple people can push changes to a shared 13.427 + repository.</para> 13.428 + 13.429 + <para id="x_477">Typically, the backers of the shared-push model use tools 13.430 + that actively enforce this approach. If you're using a 13.431 + centralised revision control tool such as Subversion, there's 13.432 + no way to make a choice over which model you'll use: the tool 13.433 + gives you shared-push, and if you want to do anything else, 13.434 + you'll have to roll your own approach on top (such as applying 13.435 + a patch by hand).</para> 13.436 + 13.437 + <para id="x_478">A good distributed revision control tool will 13.438 + support both models. You and your collaborators can then 13.439 + structure how you work together based on your own needs and 13.440 + preferences, not on what contortions your tools force you 13.441 + into.</para> 13.442 + </sect2> 13.443 + <sect2> 13.444 + <title>Where collaboration meets branch management</title> 13.445 + 13.446 + <para id="x_479">Once you and your team set up some shared 13.447 + repositories and start propagating changes back and forth 13.448 + between local and shared repos, you begin to face a related, 13.449 + but slightly different challenge: that of managing the 13.450 + multiple directions in which your team may be moving at once. 13.451 + Even though this subject is intimately related to how your 13.452 + team collaborates, it's dense enough to merit treatment of its 13.453 + own, in <xref linkend="chap:branch"/>.</para> 13.454 + </sect2> 13.455 + </sect1> 13.456 + 13.457 + <sect1> 13.458 + <title>The technical side of sharing</title> 13.459 + 13.460 + <para id="x_47a">The remainder of this chapter is devoted to the question of 13.461 + sharing changes with your collaborators.</para> 13.462 + </sect1> 13.463 + 13.464 + <sect1 id="sec:collab:serve"> 13.465 + <title>Informal sharing with <command role="hg-cmd">hg 13.466 + serve</command></title> 13.467 + 13.468 + <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command> 13.469 + command is wonderfully suited to small, tight-knit, and 13.470 + fast-paced group environments. It also provides a great way to 13.471 + get a feel for using Mercurial commands over a network.</para> 13.472 + 13.473 + <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a 13.474 + repository, and in under a second it will bring up a specialised 13.475 + HTTP server; this will accept connections from any client, and 13.476 + serve up data for that repository until you terminate it. 13.477 + Anyone who knows the URL of the server you just started, and can 13.478 + talk to your computer over the network, can then use a web 13.479 + browser or Mercurial to read data from that repository. A URL 13.480 + for a <command role="hg-cmd">hg serve</command> instance running 13.481 + on a laptop is likely to look something like 13.482 + <literal>http://my-laptop.local:8000/</literal>.</para> 13.483 + 13.484 + <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is 13.485 + <emphasis>not</emphasis> a general-purpose web server. It can do 13.486 + only two things:</para> 13.487 + <itemizedlist> 13.488 + <listitem><para id="x_47e">Allow people to browse the history of the 13.489 + repository it's serving, from their normal web 13.490 + browsers.</para> 13.491 + </listitem> 13.492 + <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people 13.493 + can <command role="hg-cmd">hg clone</command> or <command 13.494 + role="hg-cmd">hg pull</command> changes from that 13.495 + repository.</para> 13.496 + </listitem></itemizedlist> 13.497 + <para id="x_480">In particular, <command role="hg-cmd">hg serve</command> 13.498 + won't allow remote users to <emphasis>modify</emphasis> your 13.499 + repository. It's intended for read-only use.</para> 13.500 + 13.501 + <para id="x_481">If you're getting started with Mercurial, there's nothing to 13.502 + prevent you from using <command role="hg-cmd">hg serve</command> 13.503 + to serve up a repository on your own computer, then use commands 13.504 + like <command role="hg-cmd">hg clone</command>, <command 13.505 + role="hg-cmd">hg incoming</command>, and so on to talk to that 13.506 + server as if the repository was hosted remotely. This can help 13.507 + you to quickly get acquainted with using commands on 13.508 + network-hosted repositories.</para> 13.509 + 13.510 + <sect2> 13.511 + <title>A few things to keep in mind</title> 13.512 + 13.513 + <para id="x_482">Because it provides unauthenticated read access to all 13.514 + clients, you should only use <command role="hg-cmd">hg 13.515 + serve</command> in an environment where you either don't 13.516 + care, or have complete control over, who can access your 13.517 + network and pull data from your repository.</para> 13.518 + 13.519 + <para id="x_483">The <command role="hg-cmd">hg serve</command> command 13.520 + knows nothing about any firewall software you might have 13.521 + installed on your system or network. It cannot detect or 13.522 + control your firewall software. If other people are unable to 13.523 + talk to a running <command role="hg-cmd">hg serve</command> 13.524 + instance, the second thing you should do 13.525 + (<emphasis>after</emphasis> you make sure that they're using 13.526 + the correct URL) is check your firewall configuration.</para> 13.527 + 13.528 + <para id="x_484">By default, <command role="hg-cmd">hg serve</command> 13.529 + listens for incoming connections on port 8000. If another 13.530 + process is already listening on the port you want to use, you 13.531 + can specify a different port to listen on using the <option 13.532 + role="hg-opt-serve">-p</option> option.</para> 13.533 + 13.534 + <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command> 13.535 + starts, it prints no output, which can be a bit unnerving. If 13.536 + you'd like to confirm that it is indeed running correctly, and 13.537 + find out what URL you should send to your collaborators, start 13.538 + it with the <option role="hg-opt-global">-v</option> 13.539 + option.</para> 13.540 + </sect2> 13.541 + </sect1> 13.542 + 13.543 + <sect1 id="sec:collab:ssh"> 13.544 + <title>Using the Secure Shell (ssh) protocol</title> 13.545 + 13.546 + <para id="x_486">You can pull and push changes securely over a network 13.547 + connection using the Secure Shell (<literal>ssh</literal>) 13.548 + protocol. To use this successfully, you may have to do a little 13.549 + bit of configuration on the client or server sides.</para> 13.550 + 13.551 + <para id="x_487">If you're not familiar with ssh, it's the name of 13.552 + both a command and a network protocol that let you securely 13.553 + communicate with another computer. To use it with Mercurial, 13.554 + you'll be setting up one or more user accounts on a server so 13.555 + that remote users can log in and execute commands.</para> 13.556 + 13.557 + <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll 13.558 + probably find some of the material that follows to be elementary 13.559 + in nature.)</para> 13.560 + 13.561 + <sect2> 13.562 + <title>How to read and write ssh URLs</title> 13.563 + 13.564 + <para id="x_489">An ssh URL tends to look like this:</para> 13.565 + <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting> 13.566 + <orderedlist> 13.567 + <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote> 13.568 + part tells Mercurial to use the ssh protocol.</para> 13.569 + </listitem> 13.570 + <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote> 13.571 + component indicates what username to log into the server 13.572 + as. You can leave this out if the remote username is the 13.573 + same as your local username.</para> 13.574 + </listitem> 13.575 + <listitem><para id="x_48c">The 13.576 + <quote><literal>hg.serpentine.com</literal></quote> gives 13.577 + the hostname of the server to log into.</para> 13.578 + </listitem> 13.579 + <listitem><para id="x_48d">The <quote>:22</quote> identifies the port 13.580 + number to connect to the server on. The default port is 13.581 + 22, so you only need to specify a colon and port number if 13.582 + you're <emphasis>not</emphasis> using port 22.</para> 13.583 + </listitem> 13.584 + <listitem><para id="x_48e">The remainder of the URL is the local path to 13.585 + the repository on the server.</para> 13.586 + </listitem></orderedlist> 13.587 + 13.588 + <para id="x_48f">There's plenty of scope for confusion with the path 13.589 + component of ssh URLs, as there is no standard way for tools 13.590 + to interpret it. Some programs behave differently than others 13.591 + when dealing with these paths. This isn't an ideal situation, 13.592 + but it's unlikely to change. Please read the following 13.593 + paragraphs carefully.</para> 13.594 + 13.595 + <para id="x_490">Mercurial treats the path to a repository on the server as 13.596 + relative to the remote user's home directory. For example, if 13.597 + user <literal>foo</literal> on the server has a home directory 13.598 + of <filename class="directory">/home/foo</filename>, then an 13.599 + ssh URL that contains a path component of <filename 13.600 + class="directory">bar</filename> <emphasis>really</emphasis> 13.601 + refers to the directory <filename 13.602 + class="directory">/home/foo/bar</filename>.</para> 13.603 + 13.604 + <para id="x_491">If you want to specify a path relative to another user's 13.605 + home directory, you can use a path that starts with a tilde 13.606 + character followed by the user's name (let's call them 13.607 + <literal>otheruser</literal>), like this.</para> 13.608 + <programlisting>ssh://server/~otheruser/hg/repo</programlisting> 13.609 + 13.610 + <para id="x_492">And if you really want to specify an 13.611 + <emphasis>absolute</emphasis> path on the server, begin the 13.612 + path component with two slashes, as in this example.</para> 13.613 + <programlisting>ssh://server//absolute/path</programlisting> 13.614 + </sect2> 13.615 + 13.616 + <sect2> 13.617 + <title>Finding an ssh client for your system</title> 13.618 + 13.619 + <para id="x_493">Almost every Unix-like system comes with OpenSSH 13.620 + preinstalled. If you're using such a system, run 13.621 + <literal>which ssh</literal> to find out if the 13.622 + <command>ssh</command> command is installed (it's usually in 13.623 + <filename class="directory">/usr/bin</filename>). In the 13.624 + unlikely event that it isn't present, take a look at your 13.625 + system documentation to figure out how to install it.</para> 13.626 + 13.627 + <para id="x_494">On Windows, the TortoiseHg package is bundled 13.628 + with a version of Simon Tatham's excellent 13.629 + <command>plink</command> command, and you should not need to 13.630 + do any further configuration.</para> 13.631 + </sect2> 13.632 + 13.633 + <sect2> 13.634 + <title>Generating a key pair</title> 13.635 + 13.636 + <para id="x_499">To avoid the need to repetitively type a 13.637 + password every time you need to use your ssh client, I 13.638 + recommend generating a key pair.</para> 13.639 + 13.640 + <tip> 13.641 + <title>Key pairs are not mandatory</title> 13.642 + 13.643 + <para id="x_6a4">Mercurial knows nothing about ssh authentication or key 13.644 + pairs. You can, if you like, safely ignore this section and 13.645 + the one that follows until you grow tired of repeatedly 13.646 + typing ssh passwords.</para> 13.647 + </tip> 13.648 + 13.649 + <itemizedlist> 13.650 + <listitem> 13.651 + <para id="x_6a5">On a Unix-like system, the 13.652 + <command>ssh-keygen</command> command will do the 13.653 + trick.</para> 13.654 + <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need 13.655 + to download a command named <command>puttygen</command> 13.656 + from <ulink 13.657 + url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 13.658 + PuTTY web site</ulink> to generate a key pair. See 13.659 + <ulink 13.660 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 13.661 + <command>puttygen</command> documentation</ulink> for 13.662 + details of how use the command.</para> 13.663 + </listitem> 13.664 + </itemizedlist> 13.665 + 13.666 + <para id="x_49a">When you generate a key pair, it's usually 13.667 + <emphasis>highly</emphasis> advisable to protect it with a 13.668 + passphrase. (The only time that you might not want to do this 13.669 + is when you're using the ssh protocol for automated tasks on a 13.670 + secure network.)</para> 13.671 + 13.672 + <para id="x_49b">Simply generating a key pair isn't enough, however. 13.673 + You'll need to add the public key to the set of authorised 13.674 + keys for whatever user you're logging in remotely as. For 13.675 + servers using OpenSSH (the vast majority), this will mean 13.676 + adding the public key to a list in a file called <filename 13.677 + role="special">authorized_keys</filename> in their <filename 13.678 + role="special" class="directory">.ssh</filename> 13.679 + directory.</para> 13.680 + 13.681 + <para id="x_49c">On a Unix-like system, your public key will have a 13.682 + <filename>.pub</filename> extension. If you're using 13.683 + <command>puttygen</command> on Windows, you can save the 13.684 + public key to a file of your choosing, or paste it from the 13.685 + window it's displayed in straight into the <filename 13.686 + role="special">authorized_keys</filename> file.</para> 13.687 + </sect2> 13.688 + <sect2> 13.689 + <title>Using an authentication agent</title> 13.690 + 13.691 + <para id="x_49d">An authentication agent is a daemon that stores 13.692 + passphrases in memory (so it will forget passphrases if you 13.693 + log out and log back in again). An ssh client will notice if 13.694 + it's running, and query it for a passphrase. If there's no 13.695 + authentication agent running, or the agent doesn't store the 13.696 + necessary passphrase, you'll have to type your passphrase 13.697 + every time Mercurial tries to communicate with a server on 13.698 + your behalf (e.g. whenever you pull or push changes).</para> 13.699 + 13.700 + <para id="x_49e">The downside of storing passphrases in an agent is that 13.701 + it's possible for a well-prepared attacker to recover the 13.702 + plain text of your passphrases, in some cases even if your 13.703 + system has been power-cycled. You should make your own 13.704 + judgment as to whether this is an acceptable risk. It 13.705 + certainly saves a lot of repeated typing.</para> 13.706 + 13.707 + <itemizedlist> 13.708 + <listitem> 13.709 + <para id="x_49f">On Unix-like systems, the agent is called 13.710 + <command>ssh-agent</command>, and it's often run 13.711 + automatically for you when you log in. You'll need to use 13.712 + the <command>ssh-add</command> command to add passphrases 13.713 + to the agent's store.</para> 13.714 + </listitem> 13.715 + <listitem> 13.716 + <para id="x_6a7">On Windows, if you're using TortoiseHg, the 13.717 + <command>pageant</command> command acts as the agent. As 13.718 + with <command>puttygen</command>, you'll need to <ulink 13.719 + url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 13.720 + <command>pageant</command></ulink> from the PuTTY web 13.721 + site and read <ulink 13.722 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 13.723 + documentation</ulink>. The <command>pageant</command> 13.724 + command adds an icon to your system tray that will let you 13.725 + manage stored passphrases.</para> 13.726 + </listitem> 13.727 + </itemizedlist> 13.728 + </sect2> 13.729 + 13.730 + <sect2> 13.731 + <title>Configuring the server side properly</title> 13.732 + 13.733 + <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it, 13.734 + a variety of things can go wrong. Add Mercurial 13.735 + on top, and there's plenty more scope for head-scratching. 13.736 + Most of these potential problems occur on the server side, not 13.737 + the client side. The good news is that once you've gotten a 13.738 + configuration working, it will usually continue to work 13.739 + indefinitely.</para> 13.740 + 13.741 + <para id="x_4a1">Before you try using Mercurial to talk to an ssh server, 13.742 + it's best to make sure that you can use the normal 13.743 + <command>ssh</command> or <command>putty</command> command to 13.744 + talk to the server first. If you run into problems with using 13.745 + these commands directly, Mercurial surely won't work. Worse, 13.746 + it will obscure the underlying problem. Any time you want to 13.747 + debug ssh-related Mercurial problems, you should drop back to 13.748 + making sure that plain ssh client commands work first, 13.749 + <emphasis>before</emphasis> you worry about whether there's a 13.750 + problem with Mercurial.</para> 13.751 + 13.752 + <para id="x_4a2">The first thing to be sure of on the server side is that 13.753 + you can actually log in from another machine at all. If you 13.754 + can't use <command>ssh</command> or <command>putty</command> 13.755 + to log in, the error message you get may give you a few hints 13.756 + as to what's wrong. The most common problems are as 13.757 + follows.</para> 13.758 + <itemizedlist> 13.759 + <listitem><para id="x_4a3">If you get a <quote>connection refused</quote> 13.760 + error, either there isn't an SSH daemon running on the 13.761 + server at all, or it's inaccessible due to firewall 13.762 + configuration.</para> 13.763 + </listitem> 13.764 + <listitem><para id="x_4a4">If you get a <quote>no route to host</quote> 13.765 + error, you either have an incorrect address for the server 13.766 + or a seriously locked down firewall that won't admit its 13.767 + existence at all.</para> 13.768 + </listitem> 13.769 + <listitem><para id="x_4a5">If you get a <quote>permission denied</quote> 13.770 + error, you may have mistyped the username on the server, 13.771 + or you could have mistyped your key's passphrase or the 13.772 + remote user's password.</para> 13.773 + </listitem></itemizedlist> 13.774 + <para id="x_4a6">In summary, if you're having trouble talking to the 13.775 + server's ssh daemon, first make sure that one is running at 13.776 + all. On many systems it will be installed, but disabled, by 13.777 + default. Once you're done with this step, you should then 13.778 + check that the server's firewall is configured to allow 13.779 + incoming connections on the port the ssh daemon is listening 13.780 + on (usually 22). Don't worry about more exotic possibilities 13.781 + for misconfiguration until you've checked these two 13.782 + first.</para> 13.783 + 13.784 + <para id="x_4a7">If you're using an authentication agent on the client side 13.785 + to store passphrases for your keys, you ought to be able to 13.786 + log into the server without being prompted for a passphrase or 13.787 + a password. If you're prompted for a passphrase, there are a 13.788 + few possible culprits.</para> 13.789 + <itemizedlist> 13.790 + <listitem><para id="x_4a8">You might have forgotten to use 13.791 + <command>ssh-add</command> or <command>pageant</command> 13.792 + to store the passphrase.</para> 13.793 + </listitem> 13.794 + <listitem><para id="x_4a9">You might have stored the passphrase for the 13.795 + wrong key.</para> 13.796 + </listitem></itemizedlist> 13.797 + <para id="x_4aa">If you're being prompted for the remote user's password, 13.798 + there are another few possible problems to check.</para> 13.799 + <itemizedlist> 13.800 + <listitem><para id="x_4ab">Either the user's home directory or their 13.801 + <filename role="special" class="directory">.ssh</filename> 13.802 + directory might have excessively liberal permissions. As 13.803 + a result, the ssh daemon will not trust or read their 13.804 + <filename role="special">authorized_keys</filename> file. 13.805 + For example, a group-writable home or <filename 13.806 + role="special" class="directory">.ssh</filename> 13.807 + directory will often cause this symptom.</para> 13.808 + </listitem> 13.809 + <listitem><para id="x_4ac">The user's <filename 13.810 + role="special">authorized_keys</filename> file may have 13.811 + a problem. If anyone other than the user owns or can write 13.812 + to that file, the ssh daemon will not trust or read 13.813 + it.</para> 13.814 + </listitem></itemizedlist> 13.815 + 13.816 + <para id="x_4ad">In the ideal world, you should be able to run the 13.817 + following command successfully, and it should print exactly 13.818 + one line of output, the current date and time.</para> 13.819 + <programlisting>ssh myserver date</programlisting> 13.820 + 13.821 + <para id="x_4ae">If, on your server, you have login scripts that print 13.822 + banners or other junk even when running non-interactive 13.823 + commands like this, you should fix them before you continue, 13.824 + so that they only print output if they're run interactively. 13.825 + Otherwise these banners will at least clutter up Mercurial's 13.826 + output. Worse, they could potentially cause problems with 13.827 + running Mercurial commands remotely. Mercurial tries to 13.828 + detect and ignore banners in non-interactive 13.829 + <command>ssh</command> sessions, but it is not foolproof. (If 13.830 + you're editing your login scripts on your server, the usual 13.831 + way to see if a login script is running in an interactive 13.832 + shell is to check the return code from the command 13.833 + <literal>tty -s</literal>.)</para> 13.834 + 13.835 + <para id="x_4af">Once you've verified that plain old ssh is working with 13.836 + your server, the next step is to ensure that Mercurial runs on 13.837 + the server. The following command should run 13.838 + successfully:</para> 13.839 + 13.840 + <programlisting>ssh myserver hg version</programlisting> 13.841 + 13.842 + <para id="x_4b0">If you see an error message instead of normal <command 13.843 + role="hg-cmd">hg version</command> output, this is usually 13.844 + because you haven't installed Mercurial to <filename 13.845 + class="directory">/usr/bin</filename>. Don't worry if this 13.846 + is the case; you don't need to do that. But you should check 13.847 + for a few possible problems.</para> 13.848 + <itemizedlist> 13.849 + <listitem><para id="x_4b1">Is Mercurial really installed on the server at 13.850 + all? I know this sounds trivial, but it's worth 13.851 + checking!</para> 13.852 + </listitem> 13.853 + <listitem><para id="x_4b2">Maybe your shell's search path (usually set 13.854 + via the <envar>PATH</envar> environment variable) is 13.855 + simply misconfigured.</para> 13.856 + </listitem> 13.857 + <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment 13.858 + variable is only being set to point to the location of the 13.859 + <command>hg</command> executable if the login session is 13.860 + interactive. This can happen if you're setting the path 13.861 + in the wrong shell login script. See your shell's 13.862 + documentation for details.</para> 13.863 + </listitem> 13.864 + <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment 13.865 + variable may need to contain the path to the Mercurial 13.866 + Python modules. It might not be set at all; it could be 13.867 + incorrect; or it may be set only if the login is 13.868 + interactive.</para> 13.869 + </listitem></itemizedlist> 13.870 + 13.871 + <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command> 13.872 + over an ssh connection, well done! You've got the server and 13.873 + client sorted out. You should now be able to use Mercurial to 13.874 + access repositories hosted by that username on that server. 13.875 + If you run into problems with Mercurial and ssh at this point, 13.876 + try using the <option role="hg-opt-global">--debug</option> 13.877 + option to get a clearer picture of what's going on.</para> 13.878 + </sect2> 13.879 + <sect2> 13.880 + <title>Using compression with ssh</title> 13.881 + 13.882 + <para id="x_4b6">Mercurial does not compress data when it uses the ssh 13.883 + protocol, because the ssh protocol can transparently compress 13.884 + data. However, the default behavior of ssh clients is 13.885 + <emphasis>not</emphasis> to request compression.</para> 13.886 + 13.887 + <para id="x_4b7">Over any network other than a fast LAN (even a wireless 13.888 + network), using compression is likely to significantly speed 13.889 + up Mercurial's network operations. For example, over a WAN, 13.890 + someone measured compression as reducing the amount of time 13.891 + required to clone a particularly large repository from 51 13.892 + minutes to 17 minutes.</para> 13.893 + 13.894 + <para id="x_4b8">Both <command>ssh</command> and <command>plink</command> 13.895 + accept a <option role="cmd-opt-ssh">-C</option> option which 13.896 + turns on compression. You can easily edit your <filename 13.897 + role="special">~/.hgrc</filename> to enable compression for 13.898 + all of Mercurial's uses of the ssh protocol. Here is how to 13.899 + do so for regular <command>ssh</command> on Unix-like systems, 13.900 + for example.</para> 13.901 + <programlisting>[ui] 13.902 +ssh = ssh -C</programlisting> 13.903 + 13.904 + <para id="x_4b9">If you use <command>ssh</command> on a 13.905 + Unix-like system, you can configure it to always use 13.906 + compression when talking to your server. To do this, edit 13.907 + your <filename role="special">.ssh/config</filename> file 13.908 + (which may not yet exist), as follows.</para> 13.909 + 13.910 + <programlisting>Host hg 13.911 + Compression yes 13.912 + HostName hg.example.com</programlisting> 13.913 + 13.914 + <para id="x_4ba">This defines a hostname alias, 13.915 + <literal>hg</literal>. When you use that hostname on the 13.916 + <command>ssh</command> command line or in a Mercurial 13.917 + <literal>ssh</literal>-protocol URL, it will cause 13.918 + <command>ssh</command> to connect to 13.919 + <literal>hg.example.com</literal> and use compression. This 13.920 + gives you both a shorter name to type and compression, each of 13.921 + which is a good thing in its own right.</para> 13.922 + </sect2> 13.923 + </sect1> 13.924 + 13.925 + <sect1 id="sec:collab:cgi"> 13.926 + <title>Serving over HTTP using CGI</title> 13.927 + 13.928 + <para id="x_6a8">The simplest way to host one or more repositories in a 13.929 + permanent way is to use a web server and Mercurial's CGI 13.930 + support.</para> 13.931 + 13.932 + <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's 13.933 + CGI interface can take anything from a few moments to several 13.934 + hours.</para> 13.935 + 13.936 + <para id="x_4bc">We'll begin with the simplest of examples, and work our way 13.937 + towards a more complex configuration. Even for the most basic 13.938 + case, you're almost certainly going to need to read and modify 13.939 + your web server's configuration.</para> 13.940 + 13.941 + <note> 13.942 + <title>High pain tolerance required</title> 13.943 + 13.944 + <para id="x_4bd">Configuring a web server is a complex, fiddly, 13.945 + and highly system-dependent activity. I can't possibly give 13.946 + you instructions that will cover anything like all of the 13.947 + cases you will encounter. Please use your discretion and 13.948 + judgment in following the sections below. Be prepared to make 13.949 + plenty of mistakes, and to spend a lot of time reading your 13.950 + server's error logs.</para> 13.951 + 13.952 + <para id="x_6a9">If you don't have a strong stomach for tweaking 13.953 + configurations over and over, or a compelling need to host 13.954 + your own services, you might want to try one of the public 13.955 + hosting services that I mentioned earlier.</para> 13.956 + </note> 13.957 + 13.958 + <sect2> 13.959 + <title>Web server configuration checklist</title> 13.960 + 13.961 + <para id="x_4be">Before you continue, do take a few moments to check a few 13.962 + aspects of your system's setup.</para> 13.963 + 13.964 + <orderedlist> 13.965 + <listitem><para id="x_4bf">Do you have a web server installed 13.966 + at all? Mac OS X and some Linux distributions ship with 13.967 + Apache, but many other systems may not have a web server 13.968 + installed.</para> 13.969 + </listitem> 13.970 + <listitem><para id="x_4c0">If you have a web server installed, is it 13.971 + actually running? On most systems, even if one is 13.972 + present, it will be disabled by default.</para> 13.973 + </listitem> 13.974 + <listitem><para id="x_4c1">Is your server configured to allow you to run 13.975 + CGI programs in the directory where you plan to do so? 13.976 + Most servers default to explicitly disabling the ability 13.977 + to run CGI programs.</para> 13.978 + </listitem></orderedlist> 13.979 + 13.980 + <para id="x_4c2">If you don't have a web server installed, and don't have 13.981 + substantial experience configuring Apache, you should consider 13.982 + using the <literal>lighttpd</literal> web server instead of 13.983 + Apache. Apache has a well-deserved reputation for baroque and 13.984 + confusing configuration. While <literal>lighttpd</literal> is 13.985 + less capable in some ways than Apache, most of these 13.986 + capabilities are not relevant to serving Mercurial 13.987 + repositories. And <literal>lighttpd</literal> is undeniably 13.988 + <emphasis>much</emphasis> easier to get started with than 13.989 + Apache.</para> 13.990 + </sect2> 13.991 + 13.992 + <sect2> 13.993 + <title>Basic CGI configuration</title> 13.994 + 13.995 + <para id="x_4c3">On Unix-like systems, it's common for users to have a 13.996 + subdirectory named something like <filename 13.997 + class="directory">public_html</filename> in their home 13.998 + directory, from which they can serve up web pages. A file 13.999 + named <filename>foo</filename> in this directory will be 13.1000 + accessible at a URL of the form 13.1001 + <literal>http://www.example.com/username/foo</literal>.</para> 13.1002 + 13.1003 + <para id="x_4c4">To get started, find the <filename 13.1004 + role="special">hgweb.cgi</filename> script that should be 13.1005 + present in your Mercurial installation. If you can't quickly 13.1006 + find a local copy on your system, simply download one from the 13.1007 + master Mercurial repository at <ulink 13.1008 + url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>.</para> 13.1009 + 13.1010 + <para id="x_4c5">You'll need to copy this script into your <filename 13.1011 + class="directory">public_html</filename> directory, and 13.1012 + ensure that it's executable.</para> 13.1013 + <programlisting>cp .../hgweb.cgi ~/public_html 13.1014 +chmod 755 ~/public_html/hgweb.cgi</programlisting> 13.1015 + <para id="x_4c6">The <literal>755</literal> argument to 13.1016 + <command>chmod</command> is a little more general than just 13.1017 + making the script executable: it ensures that the script is 13.1018 + executable by anyone, and that <quote>group</quote> and 13.1019 + <quote>other</quote> write permissions are 13.1020 + <emphasis>not</emphasis> set. If you were to leave those 13.1021 + write permissions enabled, Apache's <literal>suexec</literal> 13.1022 + subsystem would likely refuse to execute the script. In fact, 13.1023 + <literal>suexec</literal> also insists that the 13.1024 + <emphasis>directory</emphasis> in which the script resides 13.1025 + must not be writable by others.</para> 13.1026 + <programlisting>chmod 755 ~/public_html</programlisting> 13.1027 + 13.1028 + <sect3 id="sec:collab:wtf"> 13.1029 + <title>What could <emphasis>possibly</emphasis> go 13.1030 + wrong?</title> 13.1031 + 13.1032 + <para id="x_4c7">Once you've copied the CGI script into place, 13.1033 + go into a web browser, and try to open the URL 13.1034 + <literal>http://myhostname/~myuser/hgweb.cgi</literal>, 13.1035 + <emphasis>but</emphasis> brace yourself for instant failure. 13.1036 + There's a high probability that trying to visit this URL 13.1037 + will fail, and there are many possible reasons for this. In 13.1038 + fact, you're likely to stumble over almost every one of the 13.1039 + possible errors below, so please read carefully. The 13.1040 + following are all of the problems I ran into on a system 13.1041 + running Fedora 7, with a fresh installation of Apache, and a 13.1042 + user account that I created specially to perform this 13.1043 + exercise.</para> 13.1044 + 13.1045 + <para id="x_4c8">Your web server may have per-user directories disabled. 13.1046 + If you're using Apache, search your config file for a 13.1047 + <literal>UserDir</literal> directive. If there's none 13.1048 + present, per-user directories will be disabled. If one 13.1049 + exists, but its value is <literal>disabled</literal>, then 13.1050 + per-user directories will be disabled. Otherwise, the 13.1051 + string after <literal>UserDir</literal> gives the name of 13.1052 + the subdirectory that Apache will look in under your home 13.1053 + directory, for example <filename 13.1054 + class="directory">public_html</filename>.</para> 13.1055 + 13.1056 + <para id="x_4c9">Your file access permissions may be too restrictive. 13.1057 + The web server must be able to traverse your home directory 13.1058 + and directories under your <filename 13.1059 + class="directory">public_html</filename> directory, and 13.1060 + read files under the latter too. Here's a quick recipe to 13.1061 + help you to make your permissions more appropriate.</para> 13.1062 + <programlisting>chmod 755 ~ 13.1063 +find ~/public_html -type d -print0 | xargs -0r chmod 755 13.1064 +find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting> 13.1065 + 13.1066 + <para id="x_4ca">The other possibility with permissions is that you might 13.1067 + get a completely empty window when you try to load the 13.1068 + script. In this case, it's likely that your access 13.1069 + permissions are <emphasis>too permissive</emphasis>. Apache's 13.1070 + <literal>suexec</literal> subsystem won't execute a script 13.1071 + that's group- or world-writable, for example.</para> 13.1072 + 13.1073 + <para id="x_4cb">Your web server may be configured to disallow execution 13.1074 + of CGI programs in your per-user web directory. Here's 13.1075 + Apache's default per-user configuration from my Fedora 13.1076 + system.</para> 13.1077 + 13.1078 + &ch06-apache-config.lst; 13.1079 + 13.1080 + <para id="x_4cc">If you find a similar-looking 13.1081 + <literal>Directory</literal> group in your Apache 13.1082 + configuration, the directive to look at inside it is 13.1083 + <literal>Options</literal>. Add <literal>ExecCGI</literal> 13.1084 + to the end of this list if it's missing, and restart the web 13.1085 + server.</para> 13.1086 + 13.1087 + <para id="x_4cd">If you find that Apache serves you the text of the CGI 13.1088 + script instead of executing it, you may need to either 13.1089 + uncomment (if already present) or add a directive like 13.1090 + this.</para> 13.1091 + <programlisting>AddHandler cgi-script .cgi</programlisting> 13.1092 + 13.1093 + <para id="x_4ce">The next possibility is that you might be served with a 13.1094 + colourful Python backtrace claiming that it can't import a 13.1095 + <literal>mercurial</literal>-related module. This is 13.1096 + actually progress! The server is now capable of executing 13.1097 + your CGI script. This error is only likely to occur if 13.1098 + you're running a private installation of Mercurial, instead 13.1099 + of a system-wide version. Remember that the web server runs 13.1100 + the CGI program without any of the environment variables 13.1101 + that you take for granted in an interactive session. If 13.1102 + this error happens to you, edit your copy of <filename 13.1103 + role="special">hgweb.cgi</filename> and follow the 13.1104 + directions inside it to correctly set your 13.1105 + <envar>PYTHONPATH</envar> environment variable.</para> 13.1106 + 13.1107 + <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be 13.1108 + served with another colourful Python backtrace: this one 13.1109 + will complain that it can't find <filename 13.1110 + class="directory">/path/to/repository</filename>. Edit 13.1111 + your <filename role="special">hgweb.cgi</filename> script 13.1112 + and replace the <filename 13.1113 + class="directory">/path/to/repository</filename> string 13.1114 + with the complete path to the repository you want to serve 13.1115 + up.</para> 13.1116 + 13.1117 + <para id="x_4d0">At this point, when you try to reload the page, you 13.1118 + should be presented with a nice HTML view of your 13.1119 + repository's history. Whew!</para> 13.1120 + </sect3> 13.1121 + 13.1122 + <sect3> 13.1123 + <title>Configuring lighttpd</title> 13.1124 + 13.1125 + <para id="x_4d1">To be exhaustive in my experiments, I tried configuring 13.1126 + the increasingly popular <literal>lighttpd</literal> web 13.1127 + server to serve the same repository as I described with 13.1128 + Apache above. I had already overcome all of the problems I 13.1129 + outlined with Apache, many of which are not server-specific. 13.1130 + As a result, I was fairly sure that my file and directory 13.1131 + permissions were good, and that my <filename 13.1132 + role="special">hgweb.cgi</filename> script was properly 13.1133 + edited.</para> 13.1134 + 13.1135 + <para id="x_4d2">Once I had Apache running, getting 13.1136 + <literal>lighttpd</literal> to serve the repository was a 13.1137 + snap (in other words, even if you're trying to use 13.1138 + <literal>lighttpd</literal>, you should read the Apache 13.1139 + section). I first had to edit the 13.1140 + <literal>mod_access</literal> section of its config file to 13.1141 + enable <literal>mod_cgi</literal> and 13.1142 + <literal>mod_userdir</literal>, both of which were disabled 13.1143 + by default on my system. I then added a few lines to the 13.1144 + end of the config file, to configure these modules.</para> 13.1145 + <programlisting>userdir.path = "public_html" 13.1146 +cgi.assign = (".cgi" => "" )</programlisting> 13.1147 + <para id="x_4d3">With this done, <literal>lighttpd</literal> ran 13.1148 + immediately for me. If I had configured 13.1149 + <literal>lighttpd</literal> before Apache, I'd almost 13.1150 + certainly have run into many of the same system-level 13.1151 + configuration problems as I did with Apache. However, I 13.1152 + found <literal>lighttpd</literal> to be noticeably easier to 13.1153 + configure than Apache, even though I've used Apache for over 13.1154 + a decade, and this was my first exposure to 13.1155 + <literal>lighttpd</literal>.</para> 13.1156 + </sect3> 13.1157 + </sect2> 13.1158 + 13.1159 + <sect2> 13.1160 + <title>Sharing multiple repositories with one CGI script</title> 13.1161 + 13.1162 + <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script 13.1163 + only lets you publish a single repository, which is an 13.1164 + annoying restriction. If you want to publish more than one 13.1165 + without wracking yourself with multiple copies of the same 13.1166 + script, each with different names, a better choice is to use 13.1167 + the <filename role="special">hgwebdir.cgi</filename> 13.1168 + script.</para> 13.1169 + 13.1170 + <para id="x_4d5">The procedure to configure <filename 13.1171 + role="special">hgwebdir.cgi</filename> is only a little more 13.1172 + involved than for <filename 13.1173 + role="special">hgweb.cgi</filename>. First, you must obtain 13.1174 + a copy of the script. If you don't have one handy, you can 13.1175 + download a copy from the master Mercurial repository at <ulink 13.1176 + url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.</para> 13.1177 + 13.1178 + <para id="x_4d6">You'll need to copy this script into your <filename 13.1179 + class="directory">public_html</filename> directory, and 13.1180 + ensure that it's executable.</para> 13.1181 + 13.1182 + <programlisting>cp .../hgwebdir.cgi ~/public_html 13.1183 +chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting> 13.1184 + 13.1185 + <para id="x_4d7">With basic configuration out of the way, try to 13.1186 + visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal> 13.1187 + in your browser. It should 13.1188 + display an empty list of repositories. If you get a blank 13.1189 + window or error message, try walking through the list of 13.1190 + potential problems in <xref 13.1191 + linkend="sec:collab:wtf"/>.</para> 13.1192 + 13.1193 + <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename> 13.1194 + script relies on an external configuration file. By default, 13.1195 + it searches for a file named <filename 13.1196 + role="special">hgweb.config</filename> in the same directory 13.1197 + as itself. You'll need to create this file, and make it 13.1198 + world-readable. The format of the file is similar to a 13.1199 + Windows <quote>ini</quote> file, as understood by Python's 13.1200 + <literal>ConfigParser</literal> 13.1201 + <citation>web:configparser</citation> module.</para> 13.1202 + 13.1203 + <para id="x_4d9">The easiest way to configure <filename 13.1204 + role="special">hgwebdir.cgi</filename> is with a section 13.1205 + named <literal>collections</literal>. This will automatically 13.1206 + publish <emphasis>every</emphasis> repository under the 13.1207 + directories you name. The section should look like 13.1208 + this:</para> 13.1209 + <programlisting>[collections] 13.1210 +/my/root = /my/root</programlisting> 13.1211 + <para id="x_4da">Mercurial interprets this by looking at the directory name 13.1212 + on the <emphasis>right</emphasis> hand side of the 13.1213 + <quote><literal>=</literal></quote> sign; finding repositories 13.1214 + in that directory hierarchy; and using the text on the 13.1215 + <emphasis>left</emphasis> to strip off matching text from the 13.1216 + names it will actually list in the web interface. The 13.1217 + remaining component of a path after this stripping has 13.1218 + occurred is called a <quote>virtual path</quote>.</para> 13.1219 + 13.1220 + <para id="x_4db">Given the example above, if we have a 13.1221 + repository whose local path is <filename 13.1222 + class="directory">/my/root/this/repo</filename>, the CGI 13.1223 + script will strip the leading <filename 13.1224 + class="directory">/my/root</filename> from the name, and 13.1225 + publish the repository with a virtual path of <filename 13.1226 + class="directory">this/repo</filename>. If the base URL for 13.1227 + our CGI script is 13.1228 + <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the 13.1229 + complete URL for that repository will be 13.1230 + <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para> 13.1231 + 13.1232 + <para id="x_4dc">If we replace <filename 13.1233 + class="directory">/my/root</filename> on the left hand side 13.1234 + of this example with <filename 13.1235 + class="directory">/my</filename>, then <filename 13.1236 + role="special">hgwebdir.cgi</filename> will only strip off 13.1237 + <filename class="directory">/my</filename> from the repository 13.1238 + name, and will give us a virtual path of <filename 13.1239 + class="directory">root/this/repo</filename> instead of 13.1240 + <filename class="directory">this/repo</filename>.</para> 13.1241 + 13.1242 + <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename> 13.1243 + script will recursively search each directory listed in the 13.1244 + <literal>collections</literal> section of its configuration 13.1245 + file, but it will <literal>not</literal> recurse into the 13.1246 + repositories it finds.</para> 13.1247 + 13.1248 + <para id="x_4de">The <literal>collections</literal> mechanism makes it easy 13.1249 + to publish many repositories in a <quote>fire and 13.1250 + forget</quote> manner. You only need to set up the CGI 13.1251 + script and configuration file one time. Afterwards, you can 13.1252 + publish or unpublish a repository at any time by simply moving 13.1253 + it into, or out of, the directory hierarchy in which you've 13.1254 + configured <filename role="special">hgwebdir.cgi</filename> to 13.1255 + look.</para> 13.1256 + 13.1257 + <sect3> 13.1258 + <title>Explicitly specifying which repositories to 13.1259 + publish</title> 13.1260 + 13.1261 + <para id="x_4df">In addition to the <literal>collections</literal> 13.1262 + mechanism, the <filename 13.1263 + role="special">hgwebdir.cgi</filename> script allows you 13.1264 + to publish a specific list of repositories. To do so, 13.1265 + create a <literal>paths</literal> section, with contents of 13.1266 + the following form.</para> 13.1267 + <programlisting>[paths] 13.1268 +repo1 = /my/path/to/some/repo 13.1269 +repo2 = /some/path/to/another</programlisting> 13.1270 + <para id="x_4e0">In this case, the virtual path (the component that will 13.1271 + appear in a URL) is on the left hand side of each 13.1272 + definition, while the path to the repository is on the 13.1273 + right. Notice that there does not need to be any 13.1274 + relationship between the virtual path you choose and the 13.1275 + location of a repository in your filesystem.</para> 13.1276 + 13.1277 + <para id="x_4e1">If you wish, you can use both the 13.1278 + <literal>collections</literal> and <literal>paths</literal> 13.1279 + mechanisms simultaneously in a single configuration 13.1280 + file.</para> 13.1281 + 13.1282 + <note> 13.1283 + <title>Beware duplicate virtual paths</title> 13.1284 + 13.1285 + <para id="x_4e2"> If several repositories have the same 13.1286 + virtual path, <filename 13.1287 + role="special">hgwebdir.cgi</filename> will not report 13.1288 + an error. Instead, it will behave unpredictably.</para> 13.1289 + </note> 13.1290 + </sect3> 13.1291 + </sect2> 13.1292 + 13.1293 + <sect2> 13.1294 + <title>Downloading source archives</title> 13.1295 + 13.1296 + <para id="x_4e3">Mercurial's web interface lets users download an archive 13.1297 + of any revision. This archive will contain a snapshot of the 13.1298 + working directory as of that revision, but it will not contain 13.1299 + a copy of the repository data.</para> 13.1300 + 13.1301 + <para id="x_4e4">By default, this feature is not enabled. To enable it, 13.1302 + you'll need to add an <envar 13.1303 + role="rc-item-web">allow_archive</envar> item to the 13.1304 + <literal role="rc-web">web</literal> section of your <filename 13.1305 + role="special">~/.hgrc</filename>; see below for details.</para> 13.1306 + </sect2> 13.1307 + <sect2> 13.1308 + <title>Web configuration options</title> 13.1309 + 13.1310 + <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg 13.1311 + serve</command> command, and the <filename 13.1312 + role="special">hgweb.cgi</filename> and <filename 13.1313 + role="special">hgwebdir.cgi</filename> scripts) have a 13.1314 + number of configuration options that you can set. These 13.1315 + belong in a section named <literal 13.1316 + role="rc-web">web</literal>.</para> 13.1317 + <itemizedlist> 13.1318 + <listitem><para id="x_4e6"><envar 13.1319 + role="rc-item-web">allow_archive</envar>: Determines 13.1320 + which (if any) archive download mechanisms Mercurial 13.1321 + supports. If you enable this feature, users of the web 13.1322 + interface will be able to download an archive of whatever 13.1323 + revision of a repository they are viewing. To enable the 13.1324 + archive feature, this item must take the form of a 13.1325 + sequence of words drawn from the list below.</para> 13.1326 + <itemizedlist> 13.1327 + <listitem><para id="x_4e7"><literal>bz2</literal>: A 13.1328 + <command>tar</command> archive, compressed using 13.1329 + <literal>bzip2</literal> compression. This has the 13.1330 + best compression ratio, but uses the most CPU time on 13.1331 + the server.</para> 13.1332 + </listitem> 13.1333 + <listitem><para id="x_4e8"><literal>gz</literal>: A 13.1334 + <command>tar</command> archive, compressed using 13.1335 + <literal>gzip</literal> compression.</para> 13.1336 + </listitem> 13.1337 + <listitem><para id="x_4e9"><literal>zip</literal>: A 13.1338 + <command>zip</command> archive, compressed using LZW 13.1339 + compression. This format has the worst compression 13.1340 + ratio, but is widely used in the Windows world.</para> 13.1341 + </listitem> 13.1342 + </itemizedlist> 13.1343 + <para id="x_4ea"> If you provide an empty list, or don't have an 13.1344 + <envar role="rc-item-web">allow_archive</envar> entry at 13.1345 + all, this feature will be disabled. Here is an example of 13.1346 + how to enable all three supported formats.</para> 13.1347 + <programlisting>[web] 13.1348 +allow_archive = bz2 gz zip</programlisting> 13.1349 + </listitem> 13.1350 + <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>: 13.1351 + Boolean. Determines whether the web interface allows 13.1352 + remote users to <command role="hg-cmd">hg pull</command> 13.1353 + and <command role="hg-cmd">hg clone</command> this 13.1354 + repository over HTTP. If set to <literal>no</literal> or 13.1355 + <literal>false</literal>, only the 13.1356 + <quote>human-oriented</quote> portion of the web interface 13.1357 + is available.</para> 13.1358 + </listitem> 13.1359 + <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>: 13.1360 + String. A free-form (but preferably brief) string 13.1361 + identifying the person or group in charge of the 13.1362 + repository. This often contains the name and email 13.1363 + address of a person or mailing list. It often makes sense 13.1364 + to place this entry in a repository's own <filename 13.1365 + role="special">.hg/hgrc</filename> file, but it can make 13.1366 + sense to use in a global <filename 13.1367 + role="special">~/.hgrc</filename> if every repository 13.1368 + has a single maintainer.</para> 13.1369 + </listitem> 13.1370 + <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>: 13.1371 + Integer. The default maximum number of changesets to 13.1372 + display in a single page of output.</para> 13.1373 + </listitem> 13.1374 + <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>: 13.1375 + Integer. The default maximum number of modified files to 13.1376 + display in a single page of output.</para> 13.1377 + </listitem> 13.1378 + <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>: 13.1379 + Integer. If the web interface displays alternating 13.1380 + <quote>stripes</quote> to make it easier to visually align 13.1381 + rows when you are looking at a table, this number controls 13.1382 + the number of rows in each stripe.</para> 13.1383 + </listitem> 13.1384 + <listitem><para id="x_4f0"><envar 13.1385 + role="rc-item-web">style</envar>: Controls the template 13.1386 + Mercurial uses to display the web interface. Mercurial 13.1387 + ships with several web templates.</para> 13.1388 + <itemizedlist> 13.1389 + <listitem> 13.1390 + <para id="x_6aa"><literal>coal</literal> is monochromatic.</para> 13.1391 + </listitem> 13.1392 + <listitem> 13.1393 + <para id="x_6ab"><literal>gitweb</literal> emulates the visual 13.1394 + style of git's web interface.</para> 13.1395 + </listitem> 13.1396 + <listitem> 13.1397 + <para id="x_6ac"><literal>monoblue</literal> uses solid blues and 13.1398 + greys.</para> 13.1399 + </listitem> 13.1400 + <listitem> 13.1401 + <para id="x_6ad"><literal>paper</literal> is the default.</para> 13.1402 + </listitem> 13.1403 + <listitem> 13.1404 + <para id="x_6ae"><literal>spartan</literal> was the default for a 13.1405 + long time.</para> 13.1406 + </listitem> 13.1407 + </itemizedlist> 13.1408 + <para id="x_6af">You can 13.1409 + also specify a custom template of your own; see 13.1410 + <xref linkend="chap:template"/> for details. Here, you can 13.1411 + see how to enable the <literal>gitweb</literal> 13.1412 + style.</para> 13.1413 + <programlisting>[web] 13.1414 +style = gitweb</programlisting> 13.1415 + </listitem> 13.1416 + <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>: 13.1417 + Path. The directory in which to search for template 13.1418 + files. By default, Mercurial searches in the directory in 13.1419 + which it was installed.</para> 13.1420 + </listitem></itemizedlist> 13.1421 + <para id="x_4f2">If you are using <filename 13.1422 + role="special">hgwebdir.cgi</filename>, you can place a few 13.1423 + configuration items in a <literal role="rc-web">web</literal> 13.1424 + section of the <filename 13.1425 + role="special">hgweb.config</filename> file instead of a 13.1426 + <filename role="special">~/.hgrc</filename> file, for 13.1427 + convenience. These items are <envar 13.1428 + role="rc-item-web">motd</envar> and <envar 13.1429 + role="rc-item-web">style</envar>.</para> 13.1430 + 13.1431 + <sect3> 13.1432 + <title>Options specific to an individual repository</title> 13.1433 + 13.1434 + <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration 13.1435 + items ought to be placed in a repository's local <filename 13.1436 + role="special">.hg/hgrc</filename>, rather than a user's 13.1437 + or global <filename role="special">~/.hgrc</filename>.</para> 13.1438 + <itemizedlist> 13.1439 + <listitem><para id="x_4f4"><envar 13.1440 + role="rc-item-web">description</envar>: String. A 13.1441 + free-form (but preferably brief) string that describes 13.1442 + the contents or purpose of the repository.</para> 13.1443 + </listitem> 13.1444 + <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>: 13.1445 + String. The name to use for the repository in the web 13.1446 + interface. This overrides the default name, which is 13.1447 + the last component of the repository's path.</para> 13.1448 + </listitem></itemizedlist> 13.1449 + </sect3> 13.1450 + 13.1451 + <sect3> 13.1452 + <title>Options specific to the <command role="hg-cmd">hg 13.1453 + serve</command> command</title> 13.1454 + 13.1455 + <para id="x_4f6">Some of the items in the <literal 13.1456 + role="rc-web">web</literal> section of a <filename 13.1457 + role="special">~/.hgrc</filename> file are only for use 13.1458 + with the <command role="hg-cmd">hg serve</command> 13.1459 + command.</para> 13.1460 + <itemizedlist> 13.1461 + <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>: 13.1462 + Path. The name of a file into which to write an access 13.1463 + log. By default, the <command role="hg-cmd">hg 13.1464 + serve</command> command writes this information to 13.1465 + standard output, not to a file. Log entries are written 13.1466 + in the standard <quote>combined</quote> file format used 13.1467 + by almost all web servers.</para> 13.1468 + </listitem> 13.1469 + <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>: 13.1470 + String. The local address on which the server should 13.1471 + listen for incoming connections. By default, the server 13.1472 + listens on all addresses.</para> 13.1473 + </listitem> 13.1474 + <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>: 13.1475 + Path. The name of a file into which to write an error 13.1476 + log. By default, the <command role="hg-cmd">hg 13.1477 + serve</command> command writes this information to 13.1478 + standard error, not to a file.</para> 13.1479 + </listitem> 13.1480 + <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>: 13.1481 + Boolean. Whether to use the IPv6 protocol. By default, 13.1482 + IPv6 is not used.</para> 13.1483 + </listitem> 13.1484 + <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>: 13.1485 + Integer. The TCP port number on which the server should 13.1486 + listen. The default port number used is 8000.</para> 13.1487 + </listitem></itemizedlist> 13.1488 + </sect3> 13.1489 + 13.1490 + <sect3> 13.1491 + <title>Choosing the right <filename 13.1492 + role="special">~/.hgrc</filename> file to add <literal 13.1493 + role="rc-web">web</literal> items to</title> 13.1494 + 13.1495 + <para id="x_4fc">It is important to remember that a web server like 13.1496 + Apache or <literal>lighttpd</literal> will run under a user 13.1497 + ID that is different to yours. CGI scripts run by your 13.1498 + server, such as <filename 13.1499 + role="special">hgweb.cgi</filename>, will usually also run 13.1500 + under that user ID.</para> 13.1501 + 13.1502 + <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to 13.1503 + your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that 13.1504 + <filename role="special">~/.hgrc</filename> file. Those 13.1505 + settings will thus only affect the behavior of the <command 13.1506 + role="hg-cmd">hg serve</command> command when you run it. 13.1507 + To cause CGI scripts to see your settings, either create a 13.1508 + <filename role="special">~/.hgrc</filename> file in the 13.1509 + home directory of the user ID that runs your web server, or 13.1510 + add those settings to a system-wide <filename 13.1511 + role="special">hgrc</filename> file.</para> 13.1512 + </sect3> 13.1513 + </sect2> 13.1514 + </sect1> 13.1515 + 13.1516 + <sect1> 13.1517 + <title>System-wide configuration</title> 13.1518 + 13.1519 + <para id="x_6b0">On Unix-like systems shared by multiple users (such as a 13.1520 + server to which people publish changes), it often makes sense to 13.1521 + set up some global default behaviors, such as what theme to use 13.1522 + in web interfaces.</para> 13.1523 + 13.1524 + <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename> 13.1525 + exists, Mercurial will read it at startup time and apply any 13.1526 + configuration settings it finds in that file. It will also look 13.1527 + for files ending in a <literal>.rc</literal> extension in a 13.1528 + directory named <filename>/etc/mercurial/hgrc.d</filename>, and 13.1529 + apply any configuration settings it finds in each of those 13.1530 + files.</para> 13.1531 + 13.1532 + <sect2> 13.1533 + <title>Making Mercurial more trusting</title> 13.1534 + 13.1535 + <para id="x_6b2">One situation in which a global <filename>hgrc</filename> 13.1536 + can be useful is if users are pulling changes owned by other 13.1537 + users. By default, Mercurial will not trust most of the 13.1538 + configuration items in a <filename>.hg/hgrc</filename> file 13.1539 + inside a repository that is owned by a different user. If we 13.1540 + clone or pull changes from such a repository, Mercurial will 13.1541 + print a warning stating that it does not trust their 13.1542 + <filename>.hg/hgrc</filename>.</para> 13.1543 + 13.1544 + <para id="x_6b3">If everyone in a particular Unix group is on the same team 13.1545 + and <emphasis>should</emphasis> trust each other's 13.1546 + configuration settings, or we want to trust particular users, 13.1547 + we can override Mercurial's skeptical defaults by creating a 13.1548 + system-wide <filename>hgrc</filename> file such as the 13.1549 + following:</para> 13.1550 + 13.1551 + <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc 13.1552 +[trusted] 13.1553 +# Trust all entries in any hgrc file owned by the "editors" or 13.1554 +# "www-data" groups. 13.1555 +groups = editors, www-data 13.1556 + 13.1557 +# Trust entries in hgrc files owned by the following users. 13.1558 +users = apache, bobo 13.1559 +</programlisting> 13.1560 + </sect2> 13.1561 + </sect1> 13.1562 +</chapter> 13.1563 + 13.1564 +<!-- 13.1565 +local variables: 13.1566 +sgml-parent-document: ("00book.xml" "book" "chapter") 13.1567 +end: 13.1568 +-->
14.1 --- a/en/ch06-filenames.xml Thu May 07 21:06:49 2009 -0700 14.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 14.3 @@ -1,451 +0,0 @@ 14.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 14.5 - 14.6 -<chapter id="chap:names"> 14.7 - <?dbhtml filename="file-names-and-pattern-matching.html"?> 14.8 - <title>File names and pattern matching</title> 14.9 - 14.10 - <para id="x_543">Mercurial provides mechanisms that let you work with file 14.11 - names in a consistent and expressive way.</para> 14.12 - 14.13 - <sect1> 14.14 - <title>Simple file naming</title> 14.15 - 14.16 - <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the 14.17 - hood</quote> to handle file names. Every command behaves 14.18 - uniformly with respect to file names. The way in which commands 14.19 - work with file names is as follows.</para> 14.20 - 14.21 - <para id="x_545">If you explicitly name real files on the command line, 14.22 - Mercurial works with exactly those files, as you would expect. 14.23 - &interaction.filenames.files;</para> 14.24 - 14.25 - <para id="x_546">When you provide a directory name, Mercurial will interpret 14.26 - this as <quote>operate on every file in this directory and its 14.27 - subdirectories</quote>. Mercurial traverses the files and 14.28 - subdirectories in a directory in alphabetical order. When it 14.29 - encounters a subdirectory, it will traverse that subdirectory 14.30 - before continuing with the current directory.</para> 14.31 - 14.32 - &interaction.filenames.dirs; 14.33 - </sect1> 14.34 - 14.35 - <sect1> 14.36 - <title>Running commands without any file names</title> 14.37 - 14.38 - <para id="x_547">Mercurial's commands that work with file names have useful 14.39 - default behaviors when you invoke them without providing any 14.40 - file names or patterns. What kind of behavior you should 14.41 - expect depends on what the command does. Here are a few rules 14.42 - of thumb you can use to predict what a command is likely to do 14.43 - if you don't give it any names to work with.</para> 14.44 - <itemizedlist> 14.45 - <listitem><para id="x_548">Most commands will operate on the entire working 14.46 - directory. This is what the <command role="hg-cmd">hg 14.47 - add</command> command does, for example.</para> 14.48 - </listitem> 14.49 - <listitem><para id="x_549">If the command has effects that are difficult or 14.50 - impossible to reverse, it will force you to explicitly 14.51 - provide at least one name or pattern (see below). This 14.52 - protects you from accidentally deleting files by running 14.53 - <command role="hg-cmd">hg remove</command> with no 14.54 - arguments, for example.</para> 14.55 - </listitem></itemizedlist> 14.56 - 14.57 - <para id="x_54a">It's easy to work around these default behaviors if they 14.58 - don't suit you. If a command normally operates on the whole 14.59 - working directory, you can invoke it on just the current 14.60 - directory and its subdirectories by giving it the name 14.61 - <quote><filename class="directory">.</filename></quote>.</para> 14.62 - 14.63 - &interaction.filenames.wdir-subdir; 14.64 - 14.65 - <para id="x_54b">Along the same lines, some commands normally print file 14.66 - names relative to the root of the repository, even if you're 14.67 - invoking them from a subdirectory. Such a command will print 14.68 - file names relative to your subdirectory if you give it explicit 14.69 - names. Here, we're going to run <command role="hg-cmd">hg 14.70 - status</command> from a subdirectory, and get it to operate on 14.71 - the entire working directory while printing file names relative 14.72 - to our subdirectory, by passing it the output of the <command 14.73 - role="hg-cmd">hg root</command> command.</para> 14.74 - 14.75 - &interaction.filenames.wdir-relname; 14.76 - </sect1> 14.77 - 14.78 - <sect1> 14.79 - <title>Telling you what's going on</title> 14.80 - 14.81 - <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the 14.82 - preceding section illustrates something else that's helpful 14.83 - about Mercurial commands. If a command operates on a file that 14.84 - you didn't name explicitly on the command line, it will usually 14.85 - print the name of the file, so that you will not be surprised 14.86 - what's going on.</para> 14.87 - 14.88 - <para id="x_54d">The principle here is of <emphasis>least 14.89 - surprise</emphasis>. If you've exactly named a file on the 14.90 - command line, there's no point in repeating it back at you. If 14.91 - Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g. 14.92 - because you provided no names, or a directory, or a pattern (see 14.93 - below), it is safest to tell you what files it's operating on.</para> 14.94 - 14.95 - <para id="x_54e">For commands that behave this way, you can silence them 14.96 - using the <option role="hg-opt-global">-q</option> option. You 14.97 - can also get them to print the name of every file, even those 14.98 - you've named explicitly, using the <option 14.99 - role="hg-opt-global">-v</option> option.</para> 14.100 - </sect1> 14.101 - 14.102 - <sect1> 14.103 - <title>Using patterns to identify files</title> 14.104 - 14.105 - <para id="x_54f">In addition to working with file and directory names, 14.106 - Mercurial lets you use <emphasis>patterns</emphasis> to identify 14.107 - files. Mercurial's pattern handling is expressive.</para> 14.108 - 14.109 - <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of 14.110 - matching file names to patterns normally falls to the shell. On 14.111 - these systems, you must explicitly tell Mercurial that a name is 14.112 - a pattern. On Windows, the shell does not expand patterns, so 14.113 - Mercurial will automatically identify names that are patterns, 14.114 - and expand them for you.</para> 14.115 - 14.116 - <para id="x_551">To provide a pattern in place of a regular name on the 14.117 - command line, the mechanism is simple:</para> 14.118 - <programlisting>syntax:patternbody</programlisting> 14.119 - <para id="x_552">That is, a pattern is identified by a short text string that 14.120 - says what kind of pattern this is, followed by a colon, followed 14.121 - by the actual pattern.</para> 14.122 - 14.123 - <para id="x_553">Mercurial supports two kinds of pattern syntax. The most 14.124 - frequently used is called <literal>glob</literal>; this is the 14.125 - same kind of pattern matching used by the Unix shell, and should 14.126 - be familiar to Windows command prompt users, too.</para> 14.127 - 14.128 - <para id="x_554">When Mercurial does automatic pattern matching on Windows, 14.129 - it uses <literal>glob</literal> syntax. You can thus omit the 14.130 - <quote><literal>glob:</literal></quote> prefix on Windows, but 14.131 - it's safe to use it, too.</para> 14.132 - 14.133 - <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets 14.134 - you specify patterns using regular expressions, also known as 14.135 - regexps.</para> 14.136 - 14.137 - <para id="x_556">By the way, in the examples that follow, notice that I'm 14.138 - careful to wrap all of my patterns in quote characters, so that 14.139 - they won't get expanded by the shell before Mercurial sees 14.140 - them.</para> 14.141 - 14.142 - <sect2> 14.143 - <title>Shell-style <literal>glob</literal> patterns</title> 14.144 - 14.145 - <para id="x_557">This is an overview of the kinds of patterns you can use 14.146 - when you're matching on glob patterns.</para> 14.147 - 14.148 - <para id="x_558">The <quote><literal>*</literal></quote> character matches 14.149 - any string, within a single directory.</para> 14.150 - 14.151 - &interaction.filenames.glob.star; 14.152 - 14.153 - <para id="x_559">The <quote><literal>**</literal></quote> pattern matches 14.154 - any string, and crosses directory boundaries. It's not a 14.155 - standard Unix glob token, but it's accepted by several popular 14.156 - Unix shells, and is very useful.</para> 14.157 - 14.158 - &interaction.filenames.glob.starstar; 14.159 - 14.160 - <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches 14.161 - any single character.</para> 14.162 - 14.163 - &interaction.filenames.glob.question; 14.164 - 14.165 - <para id="x_55b">The <quote><literal>[</literal></quote> character begins a 14.166 - <emphasis>character class</emphasis>. This matches any single 14.167 - character within the class. The class ends with a 14.168 - <quote><literal>]</literal></quote> character. A class may 14.169 - contain multiple <emphasis>range</emphasis>s of the form 14.170 - <quote><literal>a-f</literal></quote>, which is shorthand for 14.171 - <quote><literal>abcdef</literal></quote>.</para> 14.172 - 14.173 - &interaction.filenames.glob.range; 14.174 - 14.175 - <para id="x_55c">If the first character after the 14.176 - <quote><literal>[</literal></quote> in a character class is a 14.177 - <quote><literal>!</literal></quote>, it 14.178 - <emphasis>negates</emphasis> the class, making it match any 14.179 - single character not in the class.</para> 14.180 - 14.181 - <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of 14.182 - subpatterns, where the whole group matches if any subpattern 14.183 - in the group matches. The <quote><literal>,</literal></quote> 14.184 - character separates subpatterns, and 14.185 - <quote><literal>}</literal></quote> ends the group.</para> 14.186 - 14.187 - &interaction.filenames.glob.group; 14.188 - 14.189 - <sect3> 14.190 - <title>Watch out!</title> 14.191 - 14.192 - <para id="x_55e">Don't forget that if you want to match a pattern in any 14.193 - directory, you should not be using the 14.194 - <quote><literal>*</literal></quote> match-any token, as this 14.195 - will only match within one directory. Instead, use the 14.196 - <quote><literal>**</literal></quote> token. This small 14.197 - example illustrates the difference between the two.</para> 14.198 - 14.199 - &interaction.filenames.glob.star-starstar; 14.200 - </sect3> 14.201 - </sect2> 14.202 - 14.203 - <sect2> 14.204 - <title>Regular expression matching with <literal>re</literal> 14.205 - patterns</title> 14.206 - 14.207 - <para id="x_55f">Mercurial accepts the same regular expression syntax as 14.208 - the Python programming language (it uses Python's regexp 14.209 - engine internally). This is based on the Perl language's 14.210 - regexp syntax, which is the most popular dialect in use (it's 14.211 - also used in Java, for example).</para> 14.212 - 14.213 - <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail 14.214 - here, as regexps are not often used. Perl-style regexps are 14.215 - in any case already exhaustively documented on a multitude of 14.216 - web sites, and in many books. Instead, I will focus here on a 14.217 - few things you should know if you find yourself needing to use 14.218 - regexps with Mercurial.</para> 14.219 - 14.220 - <para id="x_561">A regexp is matched against an entire file name, relative 14.221 - to the root of the repository. In other words, even if you're 14.222 - already in subbdirectory <filename 14.223 - class="directory">foo</filename>, if you want to match files 14.224 - under this directory, your pattern must start with 14.225 - <quote><literal>foo/</literal></quote>.</para> 14.226 - 14.227 - <para id="x_562">One thing to note, if you're familiar with Perl-style 14.228 - regexps, is that Mercurial's are <emphasis>rooted</emphasis>. 14.229 - That is, a regexp starts matching against the beginning of a 14.230 - string; it doesn't look for a match anywhere within the 14.231 - string. To match anywhere in a string, start your pattern 14.232 - with <quote><literal>.*</literal></quote>.</para> 14.233 - </sect2> 14.234 - </sect1> 14.235 - 14.236 - <sect1> 14.237 - <title>Filtering files</title> 14.238 - 14.239 - <para id="x_563">Not only does Mercurial give you a variety of ways to 14.240 - specify files; it lets you further winnow those files using 14.241 - <emphasis>filters</emphasis>. Commands that work with file 14.242 - names accept two filtering options.</para> 14.243 - <itemizedlist> 14.244 - <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or 14.245 - <option role="hg-opt-global">--include</option>, lets you 14.246 - specify a pattern that file names must match in order to be 14.247 - processed.</para> 14.248 - </listitem> 14.249 - <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or 14.250 - <option role="hg-opt-global">--exclude</option>, gives you a 14.251 - way to <emphasis>avoid</emphasis> processing files, if they 14.252 - match this pattern.</para> 14.253 - </listitem></itemizedlist> 14.254 - <para id="x_566">You can provide multiple <option 14.255 - role="hg-opt-global">-I</option> and <option 14.256 - role="hg-opt-global">-X</option> options on the command line, 14.257 - and intermix them as you please. Mercurial interprets the 14.258 - patterns you provide using glob syntax by default (but you can 14.259 - use regexps if you need to).</para> 14.260 - 14.261 - <para id="x_567">You can read a <option role="hg-opt-global">-I</option> 14.262 - filter as <quote>process only the files that match this 14.263 - filter</quote>.</para> 14.264 - 14.265 - &interaction.filenames.filter.include; 14.266 - 14.267 - <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best 14.268 - read as <quote>process only the files that don't match this 14.269 - pattern</quote>.</para> 14.270 - 14.271 - &interaction.filenames.filter.exclude; 14.272 - </sect1> 14.273 - 14.274 - <sect1> 14.275 - <title>Permanently ignoring unwanted files and directories</title> 14.276 - 14.277 - <para id="x_569">When you create a new repository, the chances are 14.278 - that over time it will grow to contain files that ought to 14.279 - <emphasis>not</emphasis> be managed by Mercurial, but which you 14.280 - don't want to see listed every time you run <command>hg 14.281 - status</command>. For instance, <quote>build products</quote> 14.282 - are files that are created as part of a build but which should 14.283 - not be managed by a revision control system. The most common 14.284 - build products are output files produced by software tools such 14.285 - as compilers. As another example, many text editors litter a 14.286 - directory with lock files, temporary working files, and backup 14.287 - files, which it also makes no sense to manage.</para> 14.288 - 14.289 - <para id="x_6b4">To have Mercurial permanently ignore such files, create a 14.290 - file named <filename>.hgignore</filename> in the root of your 14.291 - repository. You <emphasis>should</emphasis> <command>hg 14.292 - add</command> this file so that it gets tracked with the rest of 14.293 - your repository contents, since your collaborators will probably 14.294 - find it useful too.</para> 14.295 - 14.296 - <para id="x_6b5">By default, the <filename>.hgignore</filename> file should 14.297 - contain a list of regular expressions, one per line. Empty 14.298 - lines are skipped. Most people prefer to describe the files they 14.299 - want to ignore using the <quote>glob</quote> syntax that we 14.300 - described above, so a typical <filename>.hgignore</filename> 14.301 - file will start with this directive:</para> 14.302 - 14.303 - <programlisting>syntax: glob</programlisting> 14.304 - 14.305 - <para id="x_6b6">This tells Mercurial to interpret the lines that follow as 14.306 - glob patterns, not regular expressions.</para> 14.307 - 14.308 - <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename> 14.309 - file.</para> 14.310 - 14.311 - <programlisting>syntax: glob 14.312 -# This line is a comment, and will be skipped. 14.313 -# Empty lines are skipped too. 14.314 - 14.315 -# Backup files left behind by the Emacs editor. 14.316 -*~ 14.317 - 14.318 -# Lock files used by the Emacs editor. 14.319 -# Notice that the "#" character is quoted with a backslash. 14.320 -# This prevents it from being interpreted as starting a comment. 14.321 -.\#* 14.322 - 14.323 -# Temporary files used by the vim editor. 14.324 -.*.swp 14.325 - 14.326 -# A hidden file created by the Mac OS X Finder. 14.327 -.DS_Store 14.328 -</programlisting> 14.329 - </sect1> 14.330 - 14.331 - <sect1 id="sec:names:case"> 14.332 - <title>Case sensitivity</title> 14.333 - 14.334 - <para id="x_56a">If you're working in a mixed development environment that 14.335 - contains both Linux (or other Unix) systems and Macs or Windows 14.336 - systems, you should keep in the back of your mind the knowledge 14.337 - that they treat the case (<quote>N</quote> versus 14.338 - <quote>n</quote>) of file names in incompatible ways. This is 14.339 - not very likely to affect you, and it's easy to deal with if it 14.340 - does, but it could surprise you if you don't know about 14.341 - it.</para> 14.342 - 14.343 - <para id="x_56b">Operating systems and filesystems differ in the way they 14.344 - handle the <emphasis>case</emphasis> of characters in file and 14.345 - directory names. There are three common ways to handle case in 14.346 - names.</para> 14.347 - <itemizedlist> 14.348 - <listitem><para id="x_56c">Completely case insensitive. Uppercase and 14.349 - lowercase versions of a letter are treated as identical, 14.350 - both when creating a file and during subsequent accesses. 14.351 - This is common on older DOS-based systems.</para> 14.352 - </listitem> 14.353 - <listitem><para id="x_56d">Case preserving, but insensitive. When a file 14.354 - or directory is created, the case of its name is stored, and 14.355 - can be retrieved and displayed by the operating system. 14.356 - When an existing file is being looked up, its case is 14.357 - ignored. This is the standard arrangement on Windows and 14.358 - MacOS. The names <filename>foo</filename> and 14.359 - <filename>FoO</filename> identify the same file. This 14.360 - treatment of uppercase and lowercase letters as 14.361 - interchangeable is also referred to as <emphasis>case 14.362 - folding</emphasis>.</para> 14.363 - </listitem> 14.364 - <listitem><para id="x_56e">Case sensitive. The case of a name 14.365 - is significant at all times. The names 14.366 - <filename>foo</filename> and <filename>FoO</filename> 14.367 - identify different files. This is the way Linux and Unix 14.368 - systems normally work.</para> 14.369 - </listitem></itemizedlist> 14.370 - 14.371 - <para id="x_56f">On Unix-like systems, it is possible to have any or all of 14.372 - the above ways of handling case in action at once. For example, 14.373 - if you use a USB thumb drive formatted with a FAT32 filesystem 14.374 - on a Linux system, Linux will handle names on that filesystem in 14.375 - a case preserving, but insensitive, way.</para> 14.376 - 14.377 - <sect2> 14.378 - <title>Safe, portable repository storage</title> 14.379 - 14.380 - <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case 14.381 - safe</emphasis>. It translates file names so that they can 14.382 - be safely stored on both case sensitive and case insensitive 14.383 - filesystems. This means that you can use normal file copying 14.384 - tools to transfer a Mercurial repository onto, for example, a 14.385 - USB thumb drive, and safely move that drive and repository 14.386 - back and forth between a Mac, a PC running Windows, and a 14.387 - Linux box.</para> 14.388 - 14.389 - </sect2> 14.390 - <sect2> 14.391 - <title>Detecting case conflicts</title> 14.392 - 14.393 - <para id="x_571">When operating in the working directory, Mercurial honours 14.394 - the naming policy of the filesystem where the working 14.395 - directory is located. If the filesystem is case preserving, 14.396 - but insensitive, Mercurial will treat names that differ only 14.397 - in case as the same.</para> 14.398 - 14.399 - <para id="x_572">An important aspect of this approach is that it is 14.400 - possible to commit a changeset on a case sensitive (typically 14.401 - Linux or Unix) filesystem that will cause trouble for users on 14.402 - case insensitive (usually Windows and MacOS) users. If a 14.403 - Linux user commits changes to two files, one named 14.404 - <filename>myfile.c</filename> and the other named 14.405 - <filename>MyFile.C</filename>, they will be stored correctly 14.406 - in the repository. And in the working directories of other 14.407 - Linux users, they will be correctly represented as separate 14.408 - files.</para> 14.409 - 14.410 - <para id="x_573">If a Windows or Mac user pulls this change, they will not 14.411 - initially have a problem, because Mercurial's repository 14.412 - storage mechanism is case safe. However, once they try to 14.413 - <command role="hg-cmd">hg update</command> the working 14.414 - directory to that changeset, or <command role="hg-cmd">hg 14.415 - merge</command> with that changeset, Mercurial will spot the 14.416 - conflict between the two file names that the filesystem would 14.417 - treat as the same, and forbid the update or merge from 14.418 - occurring.</para> 14.419 - </sect2> 14.420 - 14.421 - <sect2> 14.422 - <title>Fixing a case conflict</title> 14.423 - 14.424 - <para id="x_574">If you are using Windows or a Mac in a mixed environment 14.425 - where some of your collaborators are using Linux or Unix, and 14.426 - Mercurial reports a case folding conflict when you try to 14.427 - <command role="hg-cmd">hg update</command> or <command 14.428 - role="hg-cmd">hg merge</command>, the procedure to fix the 14.429 - problem is simple.</para> 14.430 - 14.431 - <para id="x_575">Just find a nearby Linux or Unix box, clone the problem 14.432 - repository onto it, and use Mercurial's <command 14.433 - role="hg-cmd">hg rename</command> command to change the 14.434 - names of any offending files or directories so that they will 14.435 - no longer cause case folding conflicts. Commit this change, 14.436 - <command role="hg-cmd">hg pull</command> or <command 14.437 - role="hg-cmd">hg push</command> it across to your Windows or 14.438 - MacOS system, and <command role="hg-cmd">hg update</command> 14.439 - to the revision with the non-conflicting names.</para> 14.440 - 14.441 - <para id="x_576">The changeset with case-conflicting names will remain in 14.442 - your project's history, and you still won't be able to 14.443 - <command role="hg-cmd">hg update</command> your working 14.444 - directory to that changeset on a Windows or MacOS system, but 14.445 - you can continue development unimpeded.</para> 14.446 - </sect2> 14.447 - </sect1> 14.448 -</chapter> 14.449 - 14.450 -<!-- 14.451 -local variables: 14.452 -sgml-parent-document: ("00book.xml" "book" "chapter") 14.453 -end: 14.454 --->
15.1 --- a/en/ch07-branch.xml Thu May 07 21:06:49 2009 -0700 15.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 15.3 @@ -1,533 +0,0 @@ 15.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 15.5 - 15.6 -<chapter id="chap:branch"> 15.7 - <?dbhtml filename="managing-releases-and-branchy-development.html"?> 15.8 - <title>Managing releases and branchy development</title> 15.9 - 15.10 - <para id="x_369">Mercurial provides several mechanisms for you to manage a 15.11 - project that is making progress on multiple fronts at once. To 15.12 - understand these mechanisms, let's first take a brief look at a 15.13 - fairly normal software project structure.</para> 15.14 - 15.15 - <para id="x_36a">Many software projects issue periodic <quote>major</quote> 15.16 - releases that contain substantial new features. In parallel, they 15.17 - may issue <quote>minor</quote> releases. These are usually 15.18 - identical to the major releases off which they're based, but with 15.19 - a few bugs fixed.</para> 15.20 - 15.21 - <para id="x_36b">In this chapter, we'll start by talking about how to keep 15.22 - records of project milestones such as releases. We'll then 15.23 - continue on to talk about the flow of work between different 15.24 - phases of a project, and how Mercurial can help you to isolate and 15.25 - manage this work.</para> 15.26 - 15.27 - <sect1> 15.28 - <title>Giving a persistent name to a revision</title> 15.29 - 15.30 - <para id="x_36c">Once you decide that you'd like to call a particular 15.31 - revision a <quote>release</quote>, it's a good idea to record 15.32 - the identity of that revision. This will let you reproduce that 15.33 - release at a later date, for whatever purpose you might need at 15.34 - the time (reproducing a bug, porting to a new platform, etc). 15.35 - &interaction.tag.init;</para> 15.36 - 15.37 - <para id="x_36d">Mercurial lets you give a permanent name to any revision 15.38 - using the <command role="hg-cmd">hg tag</command> command. Not 15.39 - surprisingly, these names are called <quote>tags</quote>.</para> 15.40 - 15.41 - &interaction.tag.tag; 15.42 - 15.43 - <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote> 15.44 - for a revision. Tags exist purely for your convenience, so that 15.45 - you have a handy permanent way to refer to a revision; Mercurial 15.46 - doesn't interpret the tag names you use in any way. Neither 15.47 - does Mercurial place any restrictions on the name of a tag, 15.48 - beyond a few that are necessary to ensure that a tag can be 15.49 - parsed unambiguously. A tag name cannot contain any of the 15.50 - following characters:</para> 15.51 - <itemizedlist> 15.52 - <listitem><para id="x_36f">Colon (ASCII 58, 15.53 - <quote><literal>:</literal></quote>)</para> 15.54 - </listitem> 15.55 - <listitem><para id="x_370">Carriage return (ASCII 13, 15.56 - <quote><literal>\r</literal></quote>)</para> 15.57 - </listitem> 15.58 - <listitem><para id="x_371">Newline (ASCII 10, 15.59 - <quote><literal>\n</literal></quote>)</para> 15.60 - </listitem></itemizedlist> 15.61 - 15.62 - <para id="x_372">You can use the <command role="hg-cmd">hg tags</command> 15.63 - command to display the tags present in your repository. In the 15.64 - output, each tagged revision is identified first by its name, 15.65 - then by revision number, and finally by the unique hash of the 15.66 - revision.</para> 15.67 - 15.68 - &interaction.tag.tags; 15.69 - 15.70 - <para id="x_373">Notice that <literal>tip</literal> is listed in the output 15.71 - of <command role="hg-cmd">hg tags</command>. The 15.72 - <literal>tip</literal> tag is a special <quote>floating</quote> 15.73 - tag, which always identifies the newest revision in the 15.74 - repository.</para> 15.75 - 15.76 - <para id="x_374">In the output of the <command role="hg-cmd">hg 15.77 - tags</command> command, tags are listed in reverse order, by 15.78 - revision number. This usually means that recent tags are listed 15.79 - before older tags. It also means that <literal>tip</literal> is 15.80 - always going to be the first tag listed in the output of 15.81 - <command role="hg-cmd">hg tags</command>.</para> 15.82 - 15.83 - <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it 15.84 - displays a revision that has tags associated with it, it will 15.85 - print those tags.</para> 15.86 - 15.87 - &interaction.tag.log; 15.88 - 15.89 - <para id="x_376">Any time you need to provide a revision ID to a Mercurial 15.90 - command, the command will accept a tag name in its place. 15.91 - Internally, Mercurial will translate your tag name into the 15.92 - corresponding revision ID, then use that.</para> 15.93 - 15.94 - &interaction.tag.log.v1.0; 15.95 - 15.96 - <para id="x_377">There's no limit on the number of tags you can have in a 15.97 - repository, or on the number of tags that a single revision can 15.98 - have. As a practical matter, it's not a great idea to have 15.99 - <quote>too many</quote> (a number which will vary from project 15.100 - to project), simply because tags are supposed to help you to 15.101 - find revisions. If you have lots of tags, the ease of using 15.102 - them to identify revisions diminishes rapidly.</para> 15.103 - 15.104 - <para id="x_378">For example, if your project has milestones as frequent as 15.105 - every few days, it's perfectly reasonable to tag each one of 15.106 - those. But if you have a continuous build system that makes 15.107 - sure every revision can be built cleanly, you'd be introducing a 15.108 - lot of noise if you were to tag every clean build. Instead, you 15.109 - could tag failed builds (on the assumption that they're rare!), 15.110 - or simply not use tags to track buildability.</para> 15.111 - 15.112 - <para id="x_379">If you want to remove a tag that you no longer want, use 15.113 - <command role="hg-cmd">hg tag --remove</command>.</para> 15.114 - 15.115 - &interaction.tag.remove; 15.116 - 15.117 - <para id="x_37a">You can also modify a tag at any time, so that it identifies 15.118 - a different revision, by simply issuing a new <command 15.119 - role="hg-cmd">hg tag</command> command. You'll have to use the 15.120 - <option role="hg-opt-tag">-f</option> option to tell Mercurial 15.121 - that you <emphasis>really</emphasis> want to update the 15.122 - tag.</para> 15.123 - 15.124 - &interaction.tag.replace; 15.125 - 15.126 - <para id="x_37b">There will still be a permanent record of the previous 15.127 - identity of the tag, but Mercurial will no longer use it. 15.128 - There's thus no penalty to tagging the wrong revision; all you 15.129 - have to do is turn around and tag the correct revision once you 15.130 - discover your error.</para> 15.131 - 15.132 - <para id="x_37c">Mercurial stores tags in a normal revision-controlled file 15.133 - in your repository. If you've created any tags, you'll find 15.134 - them in a file in the root of your repository named <filename 15.135 - role="special">.hgtags</filename>. When you run the <command 15.136 - role="hg-cmd">hg tag</command> command, Mercurial modifies 15.137 - this file, then automatically commits the change to it. This 15.138 - means that every time you run <command role="hg-cmd">hg 15.139 - tag</command>, you'll see a corresponding changeset in the 15.140 - output of <command role="hg-cmd">hg log</command>.</para> 15.141 - 15.142 - &interaction.tag.tip; 15.143 - 15.144 - <sect2> 15.145 - <title>Handling tag conflicts during a merge</title> 15.146 - 15.147 - <para id="x_37d">You won't often need to care about the <filename 15.148 - role="special">.hgtags</filename> file, but it sometimes 15.149 - makes its presence known during a merge. The format of the 15.150 - file is simple: it consists of a series of lines. Each line 15.151 - starts with a changeset hash, followed by a space, followed by 15.152 - the name of a tag.</para> 15.153 - 15.154 - <para id="x_37e">If you're resolving a conflict in the <filename 15.155 - role="special">.hgtags</filename> file during a merge, 15.156 - there's one twist to modifying the <filename 15.157 - role="special">.hgtags</filename> file: when Mercurial is 15.158 - parsing the tags in a repository, it 15.159 - <emphasis>never</emphasis> reads the working copy of the 15.160 - <filename role="special">.hgtags</filename> file. Instead, it 15.161 - reads the <emphasis>most recently committed</emphasis> 15.162 - revision of the file.</para> 15.163 - 15.164 - <para id="x_37f">An unfortunate consequence of this design is that you 15.165 - can't actually verify that your merged <filename 15.166 - role="special">.hgtags</filename> file is correct until 15.167 - <emphasis>after</emphasis> you've committed a change. So if 15.168 - you find yourself resolving a conflict on <filename 15.169 - role="special">.hgtags</filename> during a merge, be sure to 15.170 - run <command role="hg-cmd">hg tags</command> after you commit. 15.171 - If it finds an error in the <filename 15.172 - role="special">.hgtags</filename> file, it will report the 15.173 - location of the error, which you can then fix and commit. You 15.174 - should then run <command role="hg-cmd">hg tags</command> 15.175 - again, just to be sure that your fix is correct.</para> 15.176 - </sect2> 15.177 - 15.178 - <sect2> 15.179 - <title>Tags and cloning</title> 15.180 - 15.181 - <para id="x_380">You may have noticed that the <command role="hg-cmd">hg 15.182 - clone</command> command has a <option 15.183 - role="hg-opt-clone">-r</option> option that lets you clone 15.184 - an exact copy of the repository as of a particular changeset. 15.185 - The new clone will not contain any project history that comes 15.186 - after the revision you specified. This has an interaction 15.187 - with tags that can surprise the unwary.</para> 15.188 - 15.189 - <para id="x_381">Recall that a tag is stored as a revision to 15.190 - the <filename role="special">.hgtags</filename> file. When you 15.191 - create a tag, the changeset in which its recorded refers to an 15.192 - older changeset. When you run <command role="hg-cmd">hg clone 15.193 - -r foo</command> to clone a repository as of tag 15.194 - <literal>foo</literal>, the new clone <emphasis>will not 15.195 - contain any revision newer than the one the tag refers to, 15.196 - including the revision where the tag was created</emphasis>. 15.197 - The result is that you'll get exactly the right subset of the 15.198 - project's history in the new repository, but 15.199 - <emphasis>not</emphasis> the tag you might have 15.200 - expected.</para> 15.201 - </sect2> 15.202 - 15.203 - <sect2> 15.204 - <title>When permanent tags are too much</title> 15.205 - 15.206 - <para id="x_382">Since Mercurial's tags are revision controlled and carried 15.207 - around with a project's history, everyone you work with will 15.208 - see the tags you create. But giving names to revisions has 15.209 - uses beyond simply noting that revision 15.210 - <literal>4237e45506ee</literal> is really 15.211 - <literal>v2.0.2</literal>. If you're trying to track down a 15.212 - subtle bug, you might want a tag to remind you of something 15.213 - like <quote>Anne saw the symptoms with this 15.214 - revision</quote>.</para> 15.215 - 15.216 - <para id="x_383">For cases like this, what you might want to use are 15.217 - <emphasis>local</emphasis> tags. You can create a local tag 15.218 - with the <option role="hg-opt-tag">-l</option> option to the 15.219 - <command role="hg-cmd">hg tag</command> command. This will 15.220 - store the tag in a file called <filename 15.221 - role="special">.hg/localtags</filename>. Unlike <filename 15.222 - role="special">.hgtags</filename>, <filename 15.223 - role="special">.hg/localtags</filename> is not revision 15.224 - controlled. Any tags you create using <option 15.225 - role="hg-opt-tag">-l</option> remain strictly local to the 15.226 - repository you're currently working in.</para> 15.227 - </sect2> 15.228 - </sect1> 15.229 - 15.230 - <sect1> 15.231 - <title>The flow of changes&emdash;big picture vs. little</title> 15.232 - 15.233 - <para id="x_384">To return to the outline I sketched at the 15.234 - beginning of the chapter, let's think about a project that has 15.235 - multiple concurrent pieces of work under development at 15.236 - once.</para> 15.237 - 15.238 - <para id="x_385">There might be a push for a new <quote>main</quote> release; 15.239 - a new minor bugfix release to the last main release; and an 15.240 - unexpected <quote>hot fix</quote> to an old release that is now 15.241 - in maintenance mode.</para> 15.242 - 15.243 - <para id="x_386">The usual way people refer to these different concurrent 15.244 - directions of development is as <quote>branches</quote>. 15.245 - However, we've already seen numerous times that Mercurial treats 15.246 - <emphasis>all of history</emphasis> as a series of branches and 15.247 - merges. Really, what we have here is two ideas that are 15.248 - peripherally related, but which happen to share a name.</para> 15.249 - <itemizedlist> 15.250 - <listitem><para id="x_387"><quote>Big picture</quote> branches represent 15.251 - the sweep of a project's evolution; people give them names, 15.252 - and talk about them in conversation.</para> 15.253 - </listitem> 15.254 - <listitem><para id="x_388"><quote>Little picture</quote> branches are 15.255 - artefacts of the day-to-day activity of developing and 15.256 - merging changes. They expose the narrative of how the code 15.257 - was developed.</para> 15.258 - </listitem></itemizedlist> 15.259 - </sect1> 15.260 - 15.261 - <sect1> 15.262 - <title>Managing big-picture branches in repositories</title> 15.263 - 15.264 - <para id="x_389">The easiest way to isolate a <quote>big picture</quote> 15.265 - branch in Mercurial is in a dedicated repository. If you have 15.266 - an existing shared repository&emdash;let's call it 15.267 - <literal>myproject</literal>&emdash;that reaches a 15.268 - <quote>1.0</quote> milestone, you can start to prepare for 15.269 - future maintenance releases on top of version 1.0 by tagging the 15.270 - revision from which you prepared the 1.0 release.</para> 15.271 - 15.272 - &interaction.branch-repo.tag; 15.273 - 15.274 - <para id="x_38a">You can then clone a new shared 15.275 - <literal>myproject-1.0.1</literal> repository as of that 15.276 - tag.</para> 15.277 - 15.278 - &interaction.branch-repo.clone; 15.279 - 15.280 - <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought 15.281 - to go into an upcoming 1.0.1 minor release, they clone the 15.282 - <literal>myproject-1.0.1</literal> repository, make their 15.283 - changes, and push them back.</para> 15.284 - 15.285 - &interaction.branch-repo.bugfix; 15.286 - 15.287 - <para id="x_38c">Meanwhile, development for 15.288 - the next major release can continue, isolated and unabated, in 15.289 - the <literal>myproject</literal> repository.</para> 15.290 - 15.291 - &interaction.branch-repo.new; 15.292 - </sect1> 15.293 - 15.294 - <sect1> 15.295 - <title>Don't repeat yourself: merging across branches</title> 15.296 - 15.297 - <para id="x_38d">In many cases, if you have a bug to fix on a maintenance 15.298 - branch, the chances are good that the bug exists on your 15.299 - project's main branch (and possibly other maintenance branches, 15.300 - too). It's a rare developer who wants to fix the same bug 15.301 - multiple times, so let's look at a few ways that Mercurial can 15.302 - help you to manage these bugfixes without duplicating your 15.303 - work.</para> 15.304 - 15.305 - <para id="x_38e">In the simplest instance, all you need to do is pull changes 15.306 - from your maintenance branch into your local clone of the target 15.307 - branch.</para> 15.308 - 15.309 - &interaction.branch-repo.pull; 15.310 - 15.311 - <para id="x_38f">You'll then need to merge the heads of the two branches, and 15.312 - push back to the main branch.</para> 15.313 - 15.314 - &interaction.branch-repo.merge; 15.315 - </sect1> 15.316 - 15.317 - <sect1> 15.318 - <title>Naming branches within one repository</title> 15.319 - 15.320 - <para id="x_390">In most instances, isolating branches in repositories is the 15.321 - right approach. Its simplicity makes it easy to understand; and 15.322 - so it's hard to make mistakes. There's a one-to-one 15.323 - relationship between branches you're working in and directories 15.324 - on your system. This lets you use normal (non-Mercurial-aware) 15.325 - tools to work on files within a branch/repository.</para> 15.326 - 15.327 - <para id="x_391">If you're more in the <quote>power user</quote> category 15.328 - (<emphasis>and</emphasis> your collaborators are too), there is 15.329 - an alternative way of handling branches that you can consider. 15.330 - I've already mentioned the human-level distinction between 15.331 - <quote>small picture</quote> and <quote>big picture</quote> 15.332 - branches. While Mercurial works with multiple <quote>small 15.333 - picture</quote> branches in a repository all the time (for 15.334 - example after you pull changes in, but before you merge them), 15.335 - it can <emphasis>also</emphasis> work with multiple <quote>big 15.336 - picture</quote> branches.</para> 15.337 - 15.338 - <para id="x_392">The key to working this way is that Mercurial lets you 15.339 - assign a persistent <emphasis>name</emphasis> to a branch. 15.340 - There always exists a branch named <literal>default</literal>. 15.341 - Even before you start naming branches yourself, you can find 15.342 - traces of the <literal>default</literal> branch if you look for 15.343 - them.</para> 15.344 - 15.345 - <para id="x_393">As an example, when you run the <command role="hg-cmd">hg 15.346 - commit</command> command, and it pops up your editor so that 15.347 - you can enter a commit message, look for a line that contains 15.348 - the text <quote><literal>HG: branch default</literal></quote> at 15.349 - the bottom. This is telling you that your commit will occur on 15.350 - the branch named <literal>default</literal>.</para> 15.351 - 15.352 - <para id="x_394">To start working with named branches, use the <command 15.353 - role="hg-cmd">hg branches</command> command. This command 15.354 - lists the named branches already present in your repository, 15.355 - telling you which changeset is the tip of each.</para> 15.356 - 15.357 - &interaction.branch-named.branches; 15.358 - 15.359 - <para id="x_395">Since you haven't created any named branches yet, the only 15.360 - one that exists is <literal>default</literal>.</para> 15.361 - 15.362 - <para id="x_396">To find out what the <quote>current</quote> branch is, run 15.363 - the <command role="hg-cmd">hg branch</command> command, giving 15.364 - it no arguments. This tells you what branch the parent of the 15.365 - current changeset is on.</para> 15.366 - 15.367 - &interaction.branch-named.branch; 15.368 - 15.369 - <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg 15.370 - branch</command> command again. This time, give it one 15.371 - argument: the name of the branch you want to create.</para> 15.372 - 15.373 - &interaction.branch-named.create; 15.374 - 15.375 - <para id="x_398">After you've created a branch, you might wonder what effect 15.376 - the <command role="hg-cmd">hg branch</command> command has had. 15.377 - What do the <command role="hg-cmd">hg status</command> and 15.378 - <command role="hg-cmd">hg tip</command> commands report?</para> 15.379 - 15.380 - &interaction.branch-named.status; 15.381 - 15.382 - <para id="x_399">Nothing has changed in the 15.383 - working directory, and there's been no new history created. As 15.384 - this suggests, running the <command role="hg-cmd">hg 15.385 - branch</command> command has no permanent effect; it only 15.386 - tells Mercurial what branch name to use the 15.387 - <emphasis>next</emphasis> time you commit a changeset.</para> 15.388 - 15.389 - <para id="x_39a">When you commit a change, Mercurial records the name of the 15.390 - branch on which you committed. Once you've switched from the 15.391 - <literal>default</literal> branch to another and committed, 15.392 - you'll see the name of the new branch show up in the output of 15.393 - <command role="hg-cmd">hg log</command>, <command 15.394 - role="hg-cmd">hg tip</command>, and other commands that 15.395 - display the same kind of output.</para> 15.396 - 15.397 - &interaction.branch-named.commit; 15.398 - 15.399 - <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands 15.400 - will print the branch name of every changeset that's not on the 15.401 - <literal>default</literal> branch. As a result, if you never 15.402 - use named branches, you'll never see this information.</para> 15.403 - 15.404 - <para id="x_39c">Once you've named a branch and committed a change with that 15.405 - name, every subsequent commit that descends from that change 15.406 - will inherit the same branch name. You can change the name of a 15.407 - branch at any time, using the <command role="hg-cmd">hg 15.408 - branch</command> command.</para> 15.409 - 15.410 - &interaction.branch-named.rebranch; 15.411 - 15.412 - <para id="x_39d">In practice, this is something you won't do very often, as 15.413 - branch names tend to have fairly long lifetimes. (This isn't a 15.414 - rule, just an observation.)</para> 15.415 - </sect1> 15.416 - 15.417 - <sect1> 15.418 - <title>Dealing with multiple named branches in a 15.419 - repository</title> 15.420 - 15.421 - <para id="x_39e">If you have more than one named branch in a repository, 15.422 - Mercurial will remember the branch that your working directory 15.423 - is on when you start a command like <command role="hg-cmd">hg 15.424 - update</command> or <command role="hg-cmd">hg pull 15.425 - -u</command>. It will update the working directory to the tip 15.426 - of this branch, no matter what the <quote>repo-wide</quote> tip 15.427 - is. To update to a revision that's on a different named branch, 15.428 - you may need to use the <option role="hg-opt-update">-C</option> 15.429 - option to <command role="hg-cmd">hg update</command>.</para> 15.430 - 15.431 - <para id="x_39f">This behavior is a little subtle, so let's see it in 15.432 - action. First, let's remind ourselves what branch we're 15.433 - currently on, and what branches are in our repository.</para> 15.434 - 15.435 - &interaction.branch-named.parents; 15.436 - 15.437 - <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also 15.438 - exists an older <command role="hg-cmd">hg foo</command> 15.439 - branch.</para> 15.440 - 15.441 - <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and 15.442 - forth between the tips of the <literal>foo</literal> and 15.443 - <literal>bar</literal> branches without needing to use the 15.444 - <option role="hg-opt-update">-C</option> option, because this 15.445 - only involves going backwards and forwards linearly through our 15.446 - change history.</para> 15.447 - 15.448 - &interaction.branch-named.update-switchy; 15.449 - 15.450 - <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then 15.451 - run <command role="hg-cmd">hg update</command>, it will keep us 15.452 - on <literal>foo</literal>, not move us to the tip of 15.453 - <literal>bar</literal>.</para> 15.454 - 15.455 - &interaction.branch-named.update-nothing; 15.456 - 15.457 - <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch 15.458 - introduces a new head.</para> 15.459 - 15.460 - &interaction.branch-named.foo-commit; 15.461 - </sect1> 15.462 - 15.463 - <sect1> 15.464 - <title>Branch names and merging</title> 15.465 - 15.466 - <para id="x_3a4">As you've probably noticed, merges in Mercurial are not 15.467 - symmetrical. Let's say our repository has two heads, 17 and 23. 15.468 - If I <command role="hg-cmd">hg update</command> to 17 and then 15.469 - <command role="hg-cmd">hg merge</command> with 23, Mercurial 15.470 - records 17 as the first parent of the merge, and 23 as the 15.471 - second. Whereas if I <command role="hg-cmd">hg update</command> 15.472 - to 23 and then <command role="hg-cmd">hg merge</command> with 15.473 - 17, it records 23 as the first parent, and 17 as the 15.474 - second.</para> 15.475 - 15.476 - <para id="x_3a5">This affects Mercurial's choice of branch name when you 15.477 - merge. After a merge, Mercurial will retain the branch name of 15.478 - the first parent when you commit the result of the merge. If 15.479 - your first parent's branch name is <literal>foo</literal>, and 15.480 - you merge with <literal>bar</literal>, the branch name will 15.481 - still be <literal>foo</literal> after you merge.</para> 15.482 - 15.483 - <para id="x_3a6">It's not unusual for a repository to contain multiple heads, 15.484 - each with the same branch name. Let's say I'm working on the 15.485 - <literal>foo</literal> branch, and so are you. We commit 15.486 - different changes; I pull your changes; I now have two heads, 15.487 - each claiming to be on the <literal>foo</literal> branch. The 15.488 - result of a merge will be a single head on the 15.489 - <literal>foo</literal> branch, as you might hope.</para> 15.490 - 15.491 - <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and 15.492 - I merge work from the <literal>foo</literal> branch, the result 15.493 - will remain on the <literal>bar</literal> branch.</para> 15.494 - 15.495 - &interaction.branch-named.merge; 15.496 - 15.497 - <para id="x_3a8">To give a more concrete example, if I'm working on the 15.498 - <literal>bleeding-edge</literal> branch, and I want to bring in 15.499 - the latest fixes from the <literal>stable</literal> branch, 15.500 - Mercurial will choose the <quote>right</quote> 15.501 - (<literal>bleeding-edge</literal>) branch name when I pull and 15.502 - merge from <literal>stable</literal>.</para> 15.503 - </sect1> 15.504 - 15.505 - <sect1> 15.506 - <title>Branch naming is generally useful</title> 15.507 - 15.508 - <para id="x_3a9">You shouldn't think of named branches as applicable only to 15.509 - situations where you have multiple long-lived branches 15.510 - cohabiting in a single repository. They're very useful even in 15.511 - the one-branch-per-repository case.</para> 15.512 - 15.513 - <para id="x_3aa">In the simplest case, giving a name to each branch gives you 15.514 - a permanent record of which branch a changeset originated on. 15.515 - This gives you more context when you're trying to follow the 15.516 - history of a long-lived branchy project.</para> 15.517 - 15.518 - <para id="x_3ab">If you're working with shared repositories, you can set up a 15.519 - <literal role="hook">pretxnchangegroup</literal> hook on each 15.520 - that will block incoming changes that have the 15.521 - <quote>wrong</quote> branch name. This provides a simple, but 15.522 - effective, defence against people accidentally pushing changes 15.523 - from a <quote>bleeding edge</quote> branch to a 15.524 - <quote>stable</quote> branch. Such a hook might look like this 15.525 - inside the shared repo's <filename role="special"> 15.526 - /.hgrc</filename>.</para> 15.527 - <programlisting>[hooks] 15.528 -pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting> 15.529 - </sect1> 15.530 -</chapter> 15.531 - 15.532 -<!-- 15.533 -local variables: 15.534 -sgml-parent-document: ("00book.xml" "book" "chapter") 15.535 -end: 15.536 --->
16.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 16.2 +++ b/en/ch07-filenames.xml Thu May 07 21:07:35 2009 -0700 16.3 @@ -0,0 +1,451 @@ 16.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 16.5 + 16.6 +<chapter id="chap:names"> 16.7 + <?dbhtml filename="file-names-and-pattern-matching.html"?> 16.8 + <title>File names and pattern matching</title> 16.9 + 16.10 + <para id="x_543">Mercurial provides mechanisms that let you work with file 16.11 + names in a consistent and expressive way.</para> 16.12 + 16.13 + <sect1> 16.14 + <title>Simple file naming</title> 16.15 + 16.16 + <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the 16.17 + hood</quote> to handle file names. Every command behaves 16.18 + uniformly with respect to file names. The way in which commands 16.19 + work with file names is as follows.</para> 16.20 + 16.21 + <para id="x_545">If you explicitly name real files on the command line, 16.22 + Mercurial works with exactly those files, as you would expect. 16.23 + &interaction.filenames.files;</para> 16.24 + 16.25 + <para id="x_546">When you provide a directory name, Mercurial will interpret 16.26 + this as <quote>operate on every file in this directory and its 16.27 + subdirectories</quote>. Mercurial traverses the files and 16.28 + subdirectories in a directory in alphabetical order. When it 16.29 + encounters a subdirectory, it will traverse that subdirectory 16.30 + before continuing with the current directory.</para> 16.31 + 16.32 + &interaction.filenames.dirs; 16.33 + </sect1> 16.34 + 16.35 + <sect1> 16.36 + <title>Running commands without any file names</title> 16.37 + 16.38 + <para id="x_547">Mercurial's commands that work with file names have useful 16.39 + default behaviors when you invoke them without providing any 16.40 + file names or patterns. What kind of behavior you should 16.41 + expect depends on what the command does. Here are a few rules 16.42 + of thumb you can use to predict what a command is likely to do 16.43 + if you don't give it any names to work with.</para> 16.44 + <itemizedlist> 16.45 + <listitem><para id="x_548">Most commands will operate on the entire working 16.46 + directory. This is what the <command role="hg-cmd">hg 16.47 + add</command> command does, for example.</para> 16.48 + </listitem> 16.49 + <listitem><para id="x_549">If the command has effects that are difficult or 16.50 + impossible to reverse, it will force you to explicitly 16.51 + provide at least one name or pattern (see below). This 16.52 + protects you from accidentally deleting files by running 16.53 + <command role="hg-cmd">hg remove</command> with no 16.54 + arguments, for example.</para> 16.55 + </listitem></itemizedlist> 16.56 + 16.57 + <para id="x_54a">It's easy to work around these default behaviors if they 16.58 + don't suit you. If a command normally operates on the whole 16.59 + working directory, you can invoke it on just the current 16.60 + directory and its subdirectories by giving it the name 16.61 + <quote><filename class="directory">.</filename></quote>.</para> 16.62 + 16.63 + &interaction.filenames.wdir-subdir; 16.64 + 16.65 + <para id="x_54b">Along the same lines, some commands normally print file 16.66 + names relative to the root of the repository, even if you're 16.67 + invoking them from a subdirectory. Such a command will print 16.68 + file names relative to your subdirectory if you give it explicit 16.69 + names. Here, we're going to run <command role="hg-cmd">hg 16.70 + status</command> from a subdirectory, and get it to operate on 16.71 + the entire working directory while printing file names relative 16.72 + to our subdirectory, by passing it the output of the <command 16.73 + role="hg-cmd">hg root</command> command.</para> 16.74 + 16.75 + &interaction.filenames.wdir-relname; 16.76 + </sect1> 16.77 + 16.78 + <sect1> 16.79 + <title>Telling you what's going on</title> 16.80 + 16.81 + <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the 16.82 + preceding section illustrates something else that's helpful 16.83 + about Mercurial commands. If a command operates on a file that 16.84 + you didn't name explicitly on the command line, it will usually 16.85 + print the name of the file, so that you will not be surprised 16.86 + what's going on.</para> 16.87 + 16.88 + <para id="x_54d">The principle here is of <emphasis>least 16.89 + surprise</emphasis>. If you've exactly named a file on the 16.90 + command line, there's no point in repeating it back at you. If 16.91 + Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g. 16.92 + because you provided no names, or a directory, or a pattern (see 16.93 + below), it is safest to tell you what files it's operating on.</para> 16.94 + 16.95 + <para id="x_54e">For commands that behave this way, you can silence them 16.96 + using the <option role="hg-opt-global">-q</option> option. You 16.97 + can also get them to print the name of every file, even those 16.98 + you've named explicitly, using the <option 16.99 + role="hg-opt-global">-v</option> option.</para> 16.100 + </sect1> 16.101 + 16.102 + <sect1> 16.103 + <title>Using patterns to identify files</title> 16.104 + 16.105 + <para id="x_54f">In addition to working with file and directory names, 16.106 + Mercurial lets you use <emphasis>patterns</emphasis> to identify 16.107 + files. Mercurial's pattern handling is expressive.</para> 16.108 + 16.109 + <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of 16.110 + matching file names to patterns normally falls to the shell. On 16.111 + these systems, you must explicitly tell Mercurial that a name is 16.112 + a pattern. On Windows, the shell does not expand patterns, so 16.113 + Mercurial will automatically identify names that are patterns, 16.114 + and expand them for you.</para> 16.115 + 16.116 + <para id="x_551">To provide a pattern in place of a regular name on the 16.117 + command line, the mechanism is simple:</para> 16.118 + <programlisting>syntax:patternbody</programlisting> 16.119 + <para id="x_552">That is, a pattern is identified by a short text string that 16.120 + says what kind of pattern this is, followed by a colon, followed 16.121 + by the actual pattern.</para> 16.122 + 16.123 + <para id="x_553">Mercurial supports two kinds of pattern syntax. The most 16.124 + frequently used is called <literal>glob</literal>; this is the 16.125 + same kind of pattern matching used by the Unix shell, and should 16.126 + be familiar to Windows command prompt users, too.</para> 16.127 + 16.128 + <para id="x_554">When Mercurial does automatic pattern matching on Windows, 16.129 + it uses <literal>glob</literal> syntax. You can thus omit the 16.130 + <quote><literal>glob:</literal></quote> prefix on Windows, but 16.131 + it's safe to use it, too.</para> 16.132 + 16.133 + <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets 16.134 + you specify patterns using regular expressions, also known as 16.135 + regexps.</para> 16.136 + 16.137 + <para id="x_556">By the way, in the examples that follow, notice that I'm 16.138 + careful to wrap all of my patterns in quote characters, so that 16.139 + they won't get expanded by the shell before Mercurial sees 16.140 + them.</para> 16.141 + 16.142 + <sect2> 16.143 + <title>Shell-style <literal>glob</literal> patterns</title> 16.144 + 16.145 + <para id="x_557">This is an overview of the kinds of patterns you can use 16.146 + when you're matching on glob patterns.</para> 16.147 + 16.148 + <para id="x_558">The <quote><literal>*</literal></quote> character matches 16.149 + any string, within a single directory.</para> 16.150 + 16.151 + &interaction.filenames.glob.star; 16.152 + 16.153 + <para id="x_559">The <quote><literal>**</literal></quote> pattern matches 16.154 + any string, and crosses directory boundaries. It's not a 16.155 + standard Unix glob token, but it's accepted by several popular 16.156 + Unix shells, and is very useful.</para> 16.157 + 16.158 + &interaction.filenames.glob.starstar; 16.159 + 16.160 + <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches 16.161 + any single character.</para> 16.162 + 16.163 + &interaction.filenames.glob.question; 16.164 + 16.165 + <para id="x_55b">The <quote><literal>[</literal></quote> character begins a 16.166 + <emphasis>character class</emphasis>. This matches any single 16.167 + character within the class. The class ends with a 16.168 + <quote><literal>]</literal></quote> character. A class may 16.169 + contain multiple <emphasis>range</emphasis>s of the form 16.170 + <quote><literal>a-f</literal></quote>, which is shorthand for 16.171 + <quote><literal>abcdef</literal></quote>.</para> 16.172 + 16.173 + &interaction.filenames.glob.range; 16.174 + 16.175 + <para id="x_55c">If the first character after the 16.176 + <quote><literal>[</literal></quote> in a character class is a 16.177 + <quote><literal>!</literal></quote>, it 16.178 + <emphasis>negates</emphasis> the class, making it match any 16.179 + single character not in the class.</para> 16.180 + 16.181 + <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of 16.182 + subpatterns, where the whole group matches if any subpattern 16.183 + in the group matches. The <quote><literal>,</literal></quote> 16.184 + character separates subpatterns, and 16.185 + <quote><literal>}</literal></quote> ends the group.</para> 16.186 + 16.187 + &interaction.filenames.glob.group; 16.188 + 16.189 + <sect3> 16.190 + <title>Watch out!</title> 16.191 + 16.192 + <para id="x_55e">Don't forget that if you want to match a pattern in any 16.193 + directory, you should not be using the 16.194 + <quote><literal>*</literal></quote> match-any token, as this 16.195 + will only match within one directory. Instead, use the 16.196 + <quote><literal>**</literal></quote> token. This small 16.197 + example illustrates the difference between the two.</para> 16.198 + 16.199 + &interaction.filenames.glob.star-starstar; 16.200 + </sect3> 16.201 + </sect2> 16.202 + 16.203 + <sect2> 16.204 + <title>Regular expression matching with <literal>re</literal> 16.205 + patterns</title> 16.206 + 16.207 + <para id="x_55f">Mercurial accepts the same regular expression syntax as 16.208 + the Python programming language (it uses Python's regexp 16.209 + engine internally). This is based on the Perl language's 16.210 + regexp syntax, which is the most popular dialect in use (it's 16.211 + also used in Java, for example).</para> 16.212 + 16.213 + <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail 16.214 + here, as regexps are not often used. Perl-style regexps are 16.215 + in any case already exhaustively documented on a multitude of 16.216 + web sites, and in many books. Instead, I will focus here on a 16.217 + few things you should know if you find yourself needing to use 16.218 + regexps with Mercurial.</para> 16.219 + 16.220 + <para id="x_561">A regexp is matched against an entire file name, relative 16.221 + to the root of the repository. In other words, even if you're 16.222 + already in subbdirectory <filename 16.223 + class="directory">foo</filename>, if you want to match files 16.224 + under this directory, your pattern must start with 16.225 + <quote><literal>foo/</literal></quote>.</para> 16.226 + 16.227 + <para id="x_562">One thing to note, if you're familiar with Perl-style 16.228 + regexps, is that Mercurial's are <emphasis>rooted</emphasis>. 16.229 + That is, a regexp starts matching against the beginning of a 16.230 + string; it doesn't look for a match anywhere within the 16.231 + string. To match anywhere in a string, start your pattern 16.232 + with <quote><literal>.*</literal></quote>.</para> 16.233 + </sect2> 16.234 + </sect1> 16.235 + 16.236 + <sect1> 16.237 + <title>Filtering files</title> 16.238 + 16.239 + <para id="x_563">Not only does Mercurial give you a variety of ways to 16.240 + specify files; it lets you further winnow those files using 16.241 + <emphasis>filters</emphasis>. Commands that work with file 16.242 + names accept two filtering options.</para> 16.243 + <itemizedlist> 16.244 + <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or 16.245 + <option role="hg-opt-global">--include</option>, lets you 16.246 + specify a pattern that file names must match in order to be 16.247 + processed.</para> 16.248 + </listitem> 16.249 + <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or 16.250 + <option role="hg-opt-global">--exclude</option>, gives you a 16.251 + way to <emphasis>avoid</emphasis> processing files, if they 16.252 + match this pattern.</para> 16.253 + </listitem></itemizedlist> 16.254 + <para id="x_566">You can provide multiple <option 16.255 + role="hg-opt-global">-I</option> and <option 16.256 + role="hg-opt-global">-X</option> options on the command line, 16.257 + and intermix them as you please. Mercurial interprets the 16.258 + patterns you provide using glob syntax by default (but you can 16.259 + use regexps if you need to).</para> 16.260 + 16.261 + <para id="x_567">You can read a <option role="hg-opt-global">-I</option> 16.262 + filter as <quote>process only the files that match this 16.263 + filter</quote>.</para> 16.264 + 16.265 + &interaction.filenames.filter.include; 16.266 + 16.267 + <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best 16.268 + read as <quote>process only the files that don't match this 16.269 + pattern</quote>.</para> 16.270 + 16.271 + &interaction.filenames.filter.exclude; 16.272 + </sect1> 16.273 + 16.274 + <sect1> 16.275 + <title>Permanently ignoring unwanted files and directories</title> 16.276 + 16.277 + <para id="x_569">When you create a new repository, the chances are 16.278 + that over time it will grow to contain files that ought to 16.279 + <emphasis>not</emphasis> be managed by Mercurial, but which you 16.280 + don't want to see listed every time you run <command>hg 16.281 + status</command>. For instance, <quote>build products</quote> 16.282 + are files that are created as part of a build but which should 16.283 + not be managed by a revision control system. The most common 16.284 + build products are output files produced by software tools such 16.285 + as compilers. As another example, many text editors litter a 16.286 + directory with lock files, temporary working files, and backup 16.287 + files, which it also makes no sense to manage.</para> 16.288 + 16.289 + <para id="x_6b4">To have Mercurial permanently ignore such files, create a 16.290 + file named <filename>.hgignore</filename> in the root of your 16.291 + repository. You <emphasis>should</emphasis> <command>hg 16.292 + add</command> this file so that it gets tracked with the rest of 16.293 + your repository contents, since your collaborators will probably 16.294 + find it useful too.</para> 16.295 + 16.296 + <para id="x_6b5">By default, the <filename>.hgignore</filename> file should 16.297 + contain a list of regular expressions, one per line. Empty 16.298 + lines are skipped. Most people prefer to describe the files they 16.299 + want to ignore using the <quote>glob</quote> syntax that we 16.300 + described above, so a typical <filename>.hgignore</filename> 16.301 + file will start with this directive:</para> 16.302 + 16.303 + <programlisting>syntax: glob</programlisting> 16.304 + 16.305 + <para id="x_6b6">This tells Mercurial to interpret the lines that follow as 16.306 + glob patterns, not regular expressions.</para> 16.307 + 16.308 + <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename> 16.309 + file.</para> 16.310 + 16.311 + <programlisting>syntax: glob 16.312 +# This line is a comment, and will be skipped. 16.313 +# Empty lines are skipped too. 16.314 + 16.315 +# Backup files left behind by the Emacs editor. 16.316 +*~ 16.317 + 16.318 +# Lock files used by the Emacs editor. 16.319 +# Notice that the "#" character is quoted with a backslash. 16.320 +# This prevents it from being interpreted as starting a comment. 16.321 +.\#* 16.322 + 16.323 +# Temporary files used by the vim editor. 16.324 +.*.swp 16.325 + 16.326 +# A hidden file created by the Mac OS X Finder. 16.327 +.DS_Store 16.328 +</programlisting> 16.329 + </sect1> 16.330 + 16.331 + <sect1 id="sec:names:case"> 16.332 + <title>Case sensitivity</title> 16.333 + 16.334 + <para id="x_56a">If you're working in a mixed development environment that 16.335 + contains both Linux (or other Unix) systems and Macs or Windows 16.336 + systems, you should keep in the back of your mind the knowledge 16.337 + that they treat the case (<quote>N</quote> versus 16.338 + <quote>n</quote>) of file names in incompatible ways. This is 16.339 + not very likely to affect you, and it's easy to deal with if it 16.340 + does, but it could surprise you if you don't know about 16.341 + it.</para> 16.342 + 16.343 + <para id="x_56b">Operating systems and filesystems differ in the way they 16.344 + handle the <emphasis>case</emphasis> of characters in file and 16.345 + directory names. There are three common ways to handle case in 16.346 + names.</para> 16.347 + <itemizedlist> 16.348 + <listitem><para id="x_56c">Completely case insensitive. Uppercase and 16.349 + lowercase versions of a letter are treated as identical, 16.350 + both when creating a file and during subsequent accesses. 16.351 + This is common on older DOS-based systems.</para> 16.352 + </listitem> 16.353 + <listitem><para id="x_56d">Case preserving, but insensitive. When a file 16.354 + or directory is created, the case of its name is stored, and 16.355 + can be retrieved and displayed by the operating system. 16.356 + When an existing file is being looked up, its case is 16.357 + ignored. This is the standard arrangement on Windows and 16.358 + MacOS. The names <filename>foo</filename> and 16.359 + <filename>FoO</filename> identify the same file. This 16.360 + treatment of uppercase and lowercase letters as 16.361 + interchangeable is also referred to as <emphasis>case 16.362 + folding</emphasis>.</para> 16.363 + </listitem> 16.364 + <listitem><para id="x_56e">Case sensitive. The case of a name 16.365 + is significant at all times. The names 16.366 + <filename>foo</filename> and <filename>FoO</filename> 16.367 + identify different files. This is the way Linux and Unix 16.368 + systems normally work.</para> 16.369 + </listitem></itemizedlist> 16.370 + 16.371 + <para id="x_56f">On Unix-like systems, it is possible to have any or all of 16.372 + the above ways of handling case in action at once. For example, 16.373 + if you use a USB thumb drive formatted with a FAT32 filesystem 16.374 + on a Linux system, Linux will handle names on that filesystem in 16.375 + a case preserving, but insensitive, way.</para> 16.376 + 16.377 + <sect2> 16.378 + <title>Safe, portable repository storage</title> 16.379 + 16.380 + <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case 16.381 + safe</emphasis>. It translates file names so that they can 16.382 + be safely stored on both case sensitive and case insensitive 16.383 + filesystems. This means that you can use normal file copying 16.384 + tools to transfer a Mercurial repository onto, for example, a 16.385 + USB thumb drive, and safely move that drive and repository 16.386 + back and forth between a Mac, a PC running Windows, and a 16.387 + Linux box.</para> 16.388 + 16.389 + </sect2> 16.390 + <sect2> 16.391 + <title>Detecting case conflicts</title> 16.392 + 16.393 + <para id="x_571">When operating in the working directory, Mercurial honours 16.394 + the naming policy of the filesystem where the working 16.395 + directory is located. If the filesystem is case preserving, 16.396 + but insensitive, Mercurial will treat names that differ only 16.397 + in case as the same.</para> 16.398 + 16.399 + <para id="x_572">An important aspect of this approach is that it is 16.400 + possible to commit a changeset on a case sensitive (typically 16.401 + Linux or Unix) filesystem that will cause trouble for users on 16.402 + case insensitive (usually Windows and MacOS) users. If a 16.403 + Linux user commits changes to two files, one named 16.404 + <filename>myfile.c</filename> and the other named 16.405 + <filename>MyFile.C</filename>, they will be stored correctly 16.406 + in the repository. And in the working directories of other 16.407 + Linux users, they will be correctly represented as separate 16.408 + files.</para> 16.409 + 16.410 + <para id="x_573">If a Windows or Mac user pulls this change, they will not 16.411 + initially have a problem, because Mercurial's repository 16.412 + storage mechanism is case safe. However, once they try to 16.413 + <command role="hg-cmd">hg update</command> the working 16.414 + directory to that changeset, or <command role="hg-cmd">hg 16.415 + merge</command> with that changeset, Mercurial will spot the 16.416 + conflict between the two file names that the filesystem would 16.417 + treat as the same, and forbid the update or merge from 16.418 + occurring.</para> 16.419 + </sect2> 16.420 + 16.421 + <sect2> 16.422 + <title>Fixing a case conflict</title> 16.423 + 16.424 + <para id="x_574">If you are using Windows or a Mac in a mixed environment 16.425 + where some of your collaborators are using Linux or Unix, and 16.426 + Mercurial reports a case folding conflict when you try to 16.427 + <command role="hg-cmd">hg update</command> or <command 16.428 + role="hg-cmd">hg merge</command>, the procedure to fix the 16.429 + problem is simple.</para> 16.430 + 16.431 + <para id="x_575">Just find a nearby Linux or Unix box, clone the problem 16.432 + repository onto it, and use Mercurial's <command 16.433 + role="hg-cmd">hg rename</command> command to change the 16.434 + names of any offending files or directories so that they will 16.435 + no longer cause case folding conflicts. Commit this change, 16.436 + <command role="hg-cmd">hg pull</command> or <command 16.437 + role="hg-cmd">hg push</command> it across to your Windows or 16.438 + MacOS system, and <command role="hg-cmd">hg update</command> 16.439 + to the revision with the non-conflicting names.</para> 16.440 + 16.441 + <para id="x_576">The changeset with case-conflicting names will remain in 16.442 + your project's history, and you still won't be able to 16.443 + <command role="hg-cmd">hg update</command> your working 16.444 + directory to that changeset on a Windows or MacOS system, but 16.445 + you can continue development unimpeded.</para> 16.446 + </sect2> 16.447 + </sect1> 16.448 +</chapter> 16.449 + 16.450 +<!-- 16.451 +local variables: 16.452 +sgml-parent-document: ("00book.xml" "book" "chapter") 16.453 +end: 16.454 +-->
17.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 17.2 +++ b/en/ch08-branch.xml Thu May 07 21:07:35 2009 -0700 17.3 @@ -0,0 +1,533 @@ 17.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 17.5 + 17.6 +<chapter id="chap:branch"> 17.7 + <?dbhtml filename="managing-releases-and-branchy-development.html"?> 17.8 + <title>Managing releases and branchy development</title> 17.9 + 17.10 + <para id="x_369">Mercurial provides several mechanisms for you to manage a 17.11 + project that is making progress on multiple fronts at once. To 17.12 + understand these mechanisms, let's first take a brief look at a 17.13 + fairly normal software project structure.</para> 17.14 + 17.15 + <para id="x_36a">Many software projects issue periodic <quote>major</quote> 17.16 + releases that contain substantial new features. In parallel, they 17.17 + may issue <quote>minor</quote> releases. These are usually 17.18 + identical to the major releases off which they're based, but with 17.19 + a few bugs fixed.</para> 17.20 + 17.21 + <para id="x_36b">In this chapter, we'll start by talking about how to keep 17.22 + records of project milestones such as releases. We'll then 17.23 + continue on to talk about the flow of work between different 17.24 + phases of a project, and how Mercurial can help you to isolate and 17.25 + manage this work.</para> 17.26 + 17.27 + <sect1> 17.28 + <title>Giving a persistent name to a revision</title> 17.29 + 17.30 + <para id="x_36c">Once you decide that you'd like to call a particular 17.31 + revision a <quote>release</quote>, it's a good idea to record 17.32 + the identity of that revision. This will let you reproduce that 17.33 + release at a later date, for whatever purpose you might need at 17.34 + the time (reproducing a bug, porting to a new platform, etc). 17.35 + &interaction.tag.init;</para> 17.36 + 17.37 + <para id="x_36d">Mercurial lets you give a permanent name to any revision 17.38 + using the <command role="hg-cmd">hg tag</command> command. Not 17.39 + surprisingly, these names are called <quote>tags</quote>.</para> 17.40 + 17.41 + &interaction.tag.tag; 17.42 + 17.43 + <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote> 17.44 + for a revision. Tags exist purely for your convenience, so that 17.45 + you have a handy permanent way to refer to a revision; Mercurial 17.46 + doesn't interpret the tag names you use in any way. Neither 17.47 + does Mercurial place any restrictions on the name of a tag, 17.48 + beyond a few that are necessary to ensure that a tag can be 17.49 + parsed unambiguously. A tag name cannot contain any of the 17.50 + following characters:</para> 17.51 + <itemizedlist> 17.52 + <listitem><para id="x_36f">Colon (ASCII 58, 17.53 + <quote><literal>:</literal></quote>)</para> 17.54 + </listitem> 17.55 + <listitem><para id="x_370">Carriage return (ASCII 13, 17.56 + <quote><literal>\r</literal></quote>)</para> 17.57 + </listitem> 17.58 + <listitem><para id="x_371">Newline (ASCII 10, 17.59 + <quote><literal>\n</literal></quote>)</para> 17.60 + </listitem></itemizedlist> 17.61 + 17.62 + <para id="x_372">You can use the <command role="hg-cmd">hg tags</command> 17.63 + command to display the tags present in your repository. In the 17.64 + output, each tagged revision is identified first by its name, 17.65 + then by revision number, and finally by the unique hash of the 17.66 + revision.</para> 17.67 + 17.68 + &interaction.tag.tags; 17.69 + 17.70 + <para id="x_373">Notice that <literal>tip</literal> is listed in the output 17.71 + of <command role="hg-cmd">hg tags</command>. The 17.72 + <literal>tip</literal> tag is a special <quote>floating</quote> 17.73 + tag, which always identifies the newest revision in the 17.74 + repository.</para> 17.75 + 17.76 + <para id="x_374">In the output of the <command role="hg-cmd">hg 17.77 + tags</command> command, tags are listed in reverse order, by 17.78 + revision number. This usually means that recent tags are listed 17.79 + before older tags. It also means that <literal>tip</literal> is 17.80 + always going to be the first tag listed in the output of 17.81 + <command role="hg-cmd">hg tags</command>.</para> 17.82 + 17.83 + <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it 17.84 + displays a revision that has tags associated with it, it will 17.85 + print those tags.</para> 17.86 + 17.87 + &interaction.tag.log; 17.88 + 17.89 + <para id="x_376">Any time you need to provide a revision ID to a Mercurial 17.90 + command, the command will accept a tag name in its place. 17.91 + Internally, Mercurial will translate your tag name into the 17.92 + corresponding revision ID, then use that.</para> 17.93 + 17.94 + &interaction.tag.log.v1.0; 17.95 + 17.96 + <para id="x_377">There's no limit on the number of tags you can have in a 17.97 + repository, or on the number of tags that a single revision can 17.98 + have. As a practical matter, it's not a great idea to have 17.99 + <quote>too many</quote> (a number which will vary from project 17.100 + to project), simply because tags are supposed to help you to 17.101 + find revisions. If you have lots of tags, the ease of using 17.102 + them to identify revisions diminishes rapidly.</para> 17.103 + 17.104 + <para id="x_378">For example, if your project has milestones as frequent as 17.105 + every few days, it's perfectly reasonable to tag each one of 17.106 + those. But if you have a continuous build system that makes 17.107 + sure every revision can be built cleanly, you'd be introducing a 17.108 + lot of noise if you were to tag every clean build. Instead, you 17.109 + could tag failed builds (on the assumption that they're rare!), 17.110 + or simply not use tags to track buildability.</para> 17.111 + 17.112 + <para id="x_379">If you want to remove a tag that you no longer want, use 17.113 + <command role="hg-cmd">hg tag --remove</command>.</para> 17.114 + 17.115 + &interaction.tag.remove; 17.116 + 17.117 + <para id="x_37a">You can also modify a tag at any time, so that it identifies 17.118 + a different revision, by simply issuing a new <command 17.119 + role="hg-cmd">hg tag</command> command. You'll have to use the 17.120 + <option role="hg-opt-tag">-f</option> option to tell Mercurial 17.121 + that you <emphasis>really</emphasis> want to update the 17.122 + tag.</para> 17.123 + 17.124 + &interaction.tag.replace; 17.125 + 17.126 + <para id="x_37b">There will still be a permanent record of the previous 17.127 + identity of the tag, but Mercurial will no longer use it. 17.128 + There's thus no penalty to tagging the wrong revision; all you 17.129 + have to do is turn around and tag the correct revision once you 17.130 + discover your error.</para> 17.131 + 17.132 + <para id="x_37c">Mercurial stores tags in a normal revision-controlled file 17.133 + in your repository. If you've created any tags, you'll find 17.134 + them in a file in the root of your repository named <filename 17.135 + role="special">.hgtags</filename>. When you run the <command 17.136 + role="hg-cmd">hg tag</command> command, Mercurial modifies 17.137 + this file, then automatically commits the change to it. This 17.138 + means that every time you run <command role="hg-cmd">hg 17.139 + tag</command>, you'll see a corresponding changeset in the 17.140 + output of <command role="hg-cmd">hg log</command>.</para> 17.141 + 17.142 + &interaction.tag.tip; 17.143 + 17.144 + <sect2> 17.145 + <title>Handling tag conflicts during a merge</title> 17.146 + 17.147 + <para id="x_37d">You won't often need to care about the <filename 17.148 + role="special">.hgtags</filename> file, but it sometimes 17.149 + makes its presence known during a merge. The format of the 17.150 + file is simple: it consists of a series of lines. Each line 17.151 + starts with a changeset hash, followed by a space, followed by 17.152 + the name of a tag.</para> 17.153 + 17.154 + <para id="x_37e">If you're resolving a conflict in the <filename 17.155 + role="special">.hgtags</filename> file during a merge, 17.156 + there's one twist to modifying the <filename 17.157 + role="special">.hgtags</filename> file: when Mercurial is 17.158 + parsing the tags in a repository, it 17.159 + <emphasis>never</emphasis> reads the working copy of the 17.160 + <filename role="special">.hgtags</filename> file. Instead, it 17.161 + reads the <emphasis>most recently committed</emphasis> 17.162 + revision of the file.</para> 17.163 + 17.164 + <para id="x_37f">An unfortunate consequence of this design is that you 17.165 + can't actually verify that your merged <filename 17.166 + role="special">.hgtags</filename> file is correct until 17.167 + <emphasis>after</emphasis> you've committed a change. So if 17.168 + you find yourself resolving a conflict on <filename 17.169 + role="special">.hgtags</filename> during a merge, be sure to 17.170 + run <command role="hg-cmd">hg tags</command> after you commit. 17.171 + If it finds an error in the <filename 17.172 + role="special">.hgtags</filename> file, it will report the 17.173 + location of the error, which you can then fix and commit. You 17.174 + should then run <command role="hg-cmd">hg tags</command> 17.175 + again, just to be sure that your fix is correct.</para> 17.176 + </sect2> 17.177 + 17.178 + <sect2> 17.179 + <title>Tags and cloning</title> 17.180 + 17.181 + <para id="x_380">You may have noticed that the <command role="hg-cmd">hg 17.182 + clone</command> command has a <option 17.183 + role="hg-opt-clone">-r</option> option that lets you clone 17.184 + an exact copy of the repository as of a particular changeset. 17.185 + The new clone will not contain any project history that comes 17.186 + after the revision you specified. This has an interaction 17.187 + with tags that can surprise the unwary.</para> 17.188 + 17.189 + <para id="x_381">Recall that a tag is stored as a revision to 17.190 + the <filename role="special">.hgtags</filename> file. When you 17.191 + create a tag, the changeset in which its recorded refers to an 17.192 + older changeset. When you run <command role="hg-cmd">hg clone 17.193 + -r foo</command> to clone a repository as of tag 17.194 + <literal>foo</literal>, the new clone <emphasis>will not 17.195 + contain any revision newer than the one the tag refers to, 17.196 + including the revision where the tag was created</emphasis>. 17.197 + The result is that you'll get exactly the right subset of the 17.198 + project's history in the new repository, but 17.199 + <emphasis>not</emphasis> the tag you might have 17.200 + expected.</para> 17.201 + </sect2> 17.202 + 17.203 + <sect2> 17.204 + <title>When permanent tags are too much</title> 17.205 + 17.206 + <para id="x_382">Since Mercurial's tags are revision controlled and carried 17.207 + around with a project's history, everyone you work with will 17.208 + see the tags you create. But giving names to revisions has 17.209 + uses beyond simply noting that revision 17.210 + <literal>4237e45506ee</literal> is really 17.211 + <literal>v2.0.2</literal>. If you're trying to track down a 17.212 + subtle bug, you might want a tag to remind you of something 17.213 + like <quote>Anne saw the symptoms with this 17.214 + revision</quote>.</para> 17.215 + 17.216 + <para id="x_383">For cases like this, what you might want to use are 17.217 + <emphasis>local</emphasis> tags. You can create a local tag 17.218 + with the <option role="hg-opt-tag">-l</option> option to the 17.219 + <command role="hg-cmd">hg tag</command> command. This will 17.220 + store the tag in a file called <filename 17.221 + role="special">.hg/localtags</filename>. Unlike <filename 17.222 + role="special">.hgtags</filename>, <filename 17.223 + role="special">.hg/localtags</filename> is not revision 17.224 + controlled. Any tags you create using <option 17.225 + role="hg-opt-tag">-l</option> remain strictly local to the 17.226 + repository you're currently working in.</para> 17.227 + </sect2> 17.228 + </sect1> 17.229 + 17.230 + <sect1> 17.231 + <title>The flow of changes&emdash;big picture vs. little</title> 17.232 + 17.233 + <para id="x_384">To return to the outline I sketched at the 17.234 + beginning of the chapter, let's think about a project that has 17.235 + multiple concurrent pieces of work under development at 17.236 + once.</para> 17.237 + 17.238 + <para id="x_385">There might be a push for a new <quote>main</quote> release; 17.239 + a new minor bugfix release to the last main release; and an 17.240 + unexpected <quote>hot fix</quote> to an old release that is now 17.241 + in maintenance mode.</para> 17.242 + 17.243 + <para id="x_386">The usual way people refer to these different concurrent 17.244 + directions of development is as <quote>branches</quote>. 17.245 + However, we've already seen numerous times that Mercurial treats 17.246 + <emphasis>all of history</emphasis> as a series of branches and 17.247 + merges. Really, what we have here is two ideas that are 17.248 + peripherally related, but which happen to share a name.</para> 17.249 + <itemizedlist> 17.250 + <listitem><para id="x_387"><quote>Big picture</quote> branches represent 17.251 + the sweep of a project's evolution; people give them names, 17.252 + and talk about them in conversation.</para> 17.253 + </listitem> 17.254 + <listitem><para id="x_388"><quote>Little picture</quote> branches are 17.255 + artefacts of the day-to-day activity of developing and 17.256 + merging changes. They expose the narrative of how the code 17.257 + was developed.</para> 17.258 + </listitem></itemizedlist> 17.259 + </sect1> 17.260 + 17.261 + <sect1> 17.262 + <title>Managing big-picture branches in repositories</title> 17.263 + 17.264 + <para id="x_389">The easiest way to isolate a <quote>big picture</quote> 17.265 + branch in Mercurial is in a dedicated repository. If you have 17.266 + an existing shared repository&emdash;let's call it 17.267 + <literal>myproject</literal>&emdash;that reaches a 17.268 + <quote>1.0</quote> milestone, you can start to prepare for 17.269 + future maintenance releases on top of version 1.0 by tagging the 17.270 + revision from which you prepared the 1.0 release.</para> 17.271 + 17.272 + &interaction.branch-repo.tag; 17.273 + 17.274 + <para id="x_38a">You can then clone a new shared 17.275 + <literal>myproject-1.0.1</literal> repository as of that 17.276 + tag.</para> 17.277 + 17.278 + &interaction.branch-repo.clone; 17.279 + 17.280 + <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought 17.281 + to go into an upcoming 1.0.1 minor release, they clone the 17.282 + <literal>myproject-1.0.1</literal> repository, make their 17.283 + changes, and push them back.</para> 17.284 + 17.285 + &interaction.branch-repo.bugfix; 17.286 + 17.287 + <para id="x_38c">Meanwhile, development for 17.288 + the next major release can continue, isolated and unabated, in 17.289 + the <literal>myproject</literal> repository.</para> 17.290 + 17.291 + &interaction.branch-repo.new; 17.292 + </sect1> 17.293 + 17.294 + <sect1> 17.295 + <title>Don't repeat yourself: merging across branches</title> 17.296 + 17.297 + <para id="x_38d">In many cases, if you have a bug to fix on a maintenance 17.298 + branch, the chances are good that the bug exists on your 17.299 + project's main branch (and possibly other maintenance branches, 17.300 + too). It's a rare developer who wants to fix the same bug 17.301 + multiple times, so let's look at a few ways that Mercurial can 17.302 + help you to manage these bugfixes without duplicating your 17.303 + work.</para> 17.304 + 17.305 + <para id="x_38e">In the simplest instance, all you need to do is pull changes 17.306 + from your maintenance branch into your local clone of the target 17.307 + branch.</para> 17.308 + 17.309 + &interaction.branch-repo.pull; 17.310 + 17.311 + <para id="x_38f">You'll then need to merge the heads of the two branches, and 17.312 + push back to the main branch.</para> 17.313 + 17.314 + &interaction.branch-repo.merge; 17.315 + </sect1> 17.316 + 17.317 + <sect1> 17.318 + <title>Naming branches within one repository</title> 17.319 + 17.320 + <para id="x_390">In most instances, isolating branches in repositories is the 17.321 + right approach. Its simplicity makes it easy to understand; and 17.322 + so it's hard to make mistakes. There's a one-to-one 17.323 + relationship between branches you're working in and directories 17.324 + on your system. This lets you use normal (non-Mercurial-aware) 17.325 + tools to work on files within a branch/repository.</para> 17.326 + 17.327 + <para id="x_391">If you're more in the <quote>power user</quote> category 17.328 + (<emphasis>and</emphasis> your collaborators are too), there is 17.329 + an alternative way of handling branches that you can consider. 17.330 + I've already mentioned the human-level distinction between 17.331 + <quote>small picture</quote> and <quote>big picture</quote> 17.332 + branches. While Mercurial works with multiple <quote>small 17.333 + picture</quote> branches in a repository all the time (for 17.334 + example after you pull changes in, but before you merge them), 17.335 + it can <emphasis>also</emphasis> work with multiple <quote>big 17.336 + picture</quote> branches.</para> 17.337 + 17.338 + <para id="x_392">The key to working this way is that Mercurial lets you 17.339 + assign a persistent <emphasis>name</emphasis> to a branch. 17.340 + There always exists a branch named <literal>default</literal>. 17.341 + Even before you start naming branches yourself, you can find 17.342 + traces of the <literal>default</literal> branch if you look for 17.343 + them.</para> 17.344 + 17.345 + <para id="x_393">As an example, when you run the <command role="hg-cmd">hg 17.346 + commit</command> command, and it pops up your editor so that 17.347 + you can enter a commit message, look for a line that contains 17.348 + the text <quote><literal>HG: branch default</literal></quote> at 17.349 + the bottom. This is telling you that your commit will occur on 17.350 + the branch named <literal>default</literal>.</para> 17.351 + 17.352 + <para id="x_394">To start working with named branches, use the <command 17.353 + role="hg-cmd">hg branches</command> command. This command 17.354 + lists the named branches already present in your repository, 17.355 + telling you which changeset is the tip of each.</para> 17.356 + 17.357 + &interaction.branch-named.branches; 17.358 + 17.359 + <para id="x_395">Since you haven't created any named branches yet, the only 17.360 + one that exists is <literal>default</literal>.</para> 17.361 + 17.362 + <para id="x_396">To find out what the <quote>current</quote> branch is, run 17.363 + the <command role="hg-cmd">hg branch</command> command, giving 17.364 + it no arguments. This tells you what branch the parent of the 17.365 + current changeset is on.</para> 17.366 + 17.367 + &interaction.branch-named.branch; 17.368 + 17.369 + <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg 17.370 + branch</command> command again. This time, give it one 17.371 + argument: the name of the branch you want to create.</para> 17.372 + 17.373 + &interaction.branch-named.create; 17.374 + 17.375 + <para id="x_398">After you've created a branch, you might wonder what effect 17.376 + the <command role="hg-cmd">hg branch</command> command has had. 17.377 + What do the <command role="hg-cmd">hg status</command> and 17.378 + <command role="hg-cmd">hg tip</command> commands report?</para> 17.379 + 17.380 + &interaction.branch-named.status; 17.381 + 17.382 + <para id="x_399">Nothing has changed in the 17.383 + working directory, and there's been no new history created. As 17.384 + this suggests, running the <command role="hg-cmd">hg 17.385 + branch</command> command has no permanent effect; it only 17.386 + tells Mercurial what branch name to use the 17.387 + <emphasis>next</emphasis> time you commit a changeset.</para> 17.388 + 17.389 + <para id="x_39a">When you commit a change, Mercurial records the name of the 17.390 + branch on which you committed. Once you've switched from the 17.391 + <literal>default</literal> branch to another and committed, 17.392 + you'll see the name of the new branch show up in the output of 17.393 + <command role="hg-cmd">hg log</command>, <command 17.394 + role="hg-cmd">hg tip</command>, and other commands that 17.395 + display the same kind of output.</para> 17.396 + 17.397 + &interaction.branch-named.commit; 17.398 + 17.399 + <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands 17.400 + will print the branch name of every changeset that's not on the 17.401 + <literal>default</literal> branch. As a result, if you never 17.402 + use named branches, you'll never see this information.</para> 17.403 + 17.404 + <para id="x_39c">Once you've named a branch and committed a change with that 17.405 + name, every subsequent commit that descends from that change 17.406 + will inherit the same branch name. You can change the name of a 17.407 + branch at any time, using the <command role="hg-cmd">hg 17.408 + branch</command> command.</para> 17.409 + 17.410 + &interaction.branch-named.rebranch; 17.411 + 17.412 + <para id="x_39d">In practice, this is something you won't do very often, as 17.413 + branch names tend to have fairly long lifetimes. (This isn't a 17.414 + rule, just an observation.)</para> 17.415 + </sect1> 17.416 + 17.417 + <sect1> 17.418 + <title>Dealing with multiple named branches in a 17.419 + repository</title> 17.420 + 17.421 + <para id="x_39e">If you have more than one named branch in a repository, 17.422 + Mercurial will remember the branch that your working directory 17.423 + is on when you start a command like <command role="hg-cmd">hg 17.424 + update</command> or <command role="hg-cmd">hg pull 17.425 + -u</command>. It will update the working directory to the tip 17.426 + of this branch, no matter what the <quote>repo-wide</quote> tip 17.427 + is. To update to a revision that's on a different named branch, 17.428 + you may need to use the <option role="hg-opt-update">-C</option> 17.429 + option to <command role="hg-cmd">hg update</command>.</para> 17.430 + 17.431 + <para id="x_39f">This behavior is a little subtle, so let's see it in 17.432 + action. First, let's remind ourselves what branch we're 17.433 + currently on, and what branches are in our repository.</para> 17.434 + 17.435 + &interaction.branch-named.parents; 17.436 + 17.437 + <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also 17.438 + exists an older <command role="hg-cmd">hg foo</command> 17.439 + branch.</para> 17.440 + 17.441 + <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and 17.442 + forth between the tips of the <literal>foo</literal> and 17.443 + <literal>bar</literal> branches without needing to use the 17.444 + <option role="hg-opt-update">-C</option> option, because this 17.445 + only involves going backwards and forwards linearly through our 17.446 + change history.</para> 17.447 + 17.448 + &interaction.branch-named.update-switchy; 17.449 + 17.450 + <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then 17.451 + run <command role="hg-cmd">hg update</command>, it will keep us 17.452 + on <literal>foo</literal>, not move us to the tip of 17.453 + <literal>bar</literal>.</para> 17.454 + 17.455 + &interaction.branch-named.update-nothing; 17.456 + 17.457 + <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch 17.458 + introduces a new head.</para> 17.459 + 17.460 + &interaction.branch-named.foo-commit; 17.461 + </sect1> 17.462 + 17.463 + <sect1> 17.464 + <title>Branch names and merging</title> 17.465 + 17.466 + <para id="x_3a4">As you've probably noticed, merges in Mercurial are not 17.467 + symmetrical. Let's say our repository has two heads, 17 and 23. 17.468 + If I <command role="hg-cmd">hg update</command> to 17 and then 17.469 + <command role="hg-cmd">hg merge</command> with 23, Mercurial 17.470 + records 17 as the first parent of the merge, and 23 as the 17.471 + second. Whereas if I <command role="hg-cmd">hg update</command> 17.472 + to 23 and then <command role="hg-cmd">hg merge</command> with 17.473 + 17, it records 23 as the first parent, and 17 as the 17.474 + second.</para> 17.475 + 17.476 + <para id="x_3a5">This affects Mercurial's choice of branch name when you 17.477 + merge. After a merge, Mercurial will retain the branch name of 17.478 + the first parent when you commit the result of the merge. If 17.479 + your first parent's branch name is <literal>foo</literal>, and 17.480 + you merge with <literal>bar</literal>, the branch name will 17.481 + still be <literal>foo</literal> after you merge.</para> 17.482 + 17.483 + <para id="x_3a6">It's not unusual for a repository to contain multiple heads, 17.484 + each with the same branch name. Let's say I'm working on the 17.485 + <literal>foo</literal> branch, and so are you. We commit 17.486 + different changes; I pull your changes; I now have two heads, 17.487 + each claiming to be on the <literal>foo</literal> branch. The 17.488 + result of a merge will be a single head on the 17.489 + <literal>foo</literal> branch, as you might hope.</para> 17.490 + 17.491 + <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and 17.492 + I merge work from the <literal>foo</literal> branch, the result 17.493 + will remain on the <literal>bar</literal> branch.</para> 17.494 + 17.495 + &interaction.branch-named.merge; 17.496 + 17.497 + <para id="x_3a8">To give a more concrete example, if I'm working on the 17.498 + <literal>bleeding-edge</literal> branch, and I want to bring in 17.499 + the latest fixes from the <literal>stable</literal> branch, 17.500 + Mercurial will choose the <quote>right</quote> 17.501 + (<literal>bleeding-edge</literal>) branch name when I pull and 17.502 + merge from <literal>stable</literal>.</para> 17.503 + </sect1> 17.504 + 17.505 + <sect1> 17.506 + <title>Branch naming is generally useful</title> 17.507 + 17.508 + <para id="x_3a9">You shouldn't think of named branches as applicable only to 17.509 + situations where you have multiple long-lived branches 17.510 + cohabiting in a single repository. They're very useful even in 17.511 + the one-branch-per-repository case.</para> 17.512 + 17.513 + <para id="x_3aa">In the simplest case, giving a name to each branch gives you 17.514 + a permanent record of which branch a changeset originated on. 17.515 + This gives you more context when you're trying to follow the 17.516 + history of a long-lived branchy project.</para> 17.517 + 17.518 + <para id="x_3ab">If you're working with shared repositories, you can set up a 17.519 + <literal role="hook">pretxnchangegroup</literal> hook on each 17.520 + that will block incoming changes that have the 17.521 + <quote>wrong</quote> branch name. This provides a simple, but 17.522 + effective, defence against people accidentally pushing changes 17.523 + from a <quote>bleeding edge</quote> branch to a 17.524 + <quote>stable</quote> branch. Such a hook might look like this 17.525 + inside the shared repo's <filename role="special"> 17.526 + /.hgrc</filename>.</para> 17.527 + <programlisting>[hooks] 17.528 +pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting> 17.529 + </sect1> 17.530 +</chapter> 17.531 + 17.532 +<!-- 17.533 +local variables: 17.534 +sgml-parent-document: ("00book.xml" "book" "chapter") 17.535 +end: 17.536 +-->
18.1 --- a/en/ch08-undo.xml Thu May 07 21:06:49 2009 -0700 18.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 18.3 @@ -1,1201 +0,0 @@ 18.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 18.5 - 18.6 -<chapter id="chap:undo"> 18.7 - <?dbhtml filename="finding-and-fixing-mistakes.html"?> 18.8 - <title>Finding and fixing mistakes</title> 18.9 - 18.10 - <para id="x_d2">To err might be human, but to really handle the consequences 18.11 - well takes a top-notch revision control system. In this chapter, 18.12 - we'll discuss some of the techniques you can use when you find 18.13 - that a problem has crept into your project. Mercurial has some 18.14 - highly capable features that will help you to isolate the sources 18.15 - of problems, and to handle them appropriately.</para> 18.16 - 18.17 - <sect1> 18.18 - <title>Erasing local history</title> 18.19 - 18.20 - <sect2> 18.21 - <title>The accidental commit</title> 18.22 - 18.23 - <para id="x_d3">I have the occasional but persistent problem of typing 18.24 - rather more quickly than I can think, which sometimes results 18.25 - in me committing a changeset that is either incomplete or 18.26 - plain wrong. In my case, the usual kind of incomplete 18.27 - changeset is one in which I've created a new source file, but 18.28 - forgotten to <command role="hg-cmd">hg add</command> it. A 18.29 - <quote>plain wrong</quote> changeset is not as common, but no 18.30 - less annoying.</para> 18.31 - 18.32 - </sect2> 18.33 - <sect2 id="sec:undo:rollback"> 18.34 - <title>Rolling back a transaction</title> 18.35 - 18.36 - <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I 18.37 - mentioned that Mercurial treats each modification of a 18.38 - repository as a <emphasis>transaction</emphasis>. Every time 18.39 - you commit a changeset or pull changes from another 18.40 - repository, Mercurial remembers what you did. You can undo, 18.41 - or <emphasis>roll back</emphasis>, exactly one of these 18.42 - actions using the <command role="hg-cmd">hg rollback</command> 18.43 - command. (See <xref linkend="sec:undo:rollback-after-push"/> 18.44 - for an important caveat about the use of this command.)</para> 18.45 - 18.46 - <para id="x_d5">Here's a mistake that I often find myself making: 18.47 - committing a change in which I've created a new file, but 18.48 - forgotten to <command role="hg-cmd">hg add</command> 18.49 - it.</para> 18.50 - 18.51 - &interaction.rollback.commit; 18.52 - 18.53 - <para id="x_d6">Looking at the output of <command role="hg-cmd">hg 18.54 - status</command> after the commit immediately confirms the 18.55 - error.</para> 18.56 - 18.57 - &interaction.rollback.status; 18.58 - 18.59 - <para id="x_d7">The commit captured the changes to the file 18.60 - <filename>a</filename>, but not the new file 18.61 - <filename>b</filename>. If I were to push this changeset to a 18.62 - repository that I shared with a colleague, the chances are 18.63 - high that something in <filename>a</filename> would refer to 18.64 - <filename>b</filename>, which would not be present in their 18.65 - repository when they pulled my changes. I would thus become 18.66 - the object of some indignation.</para> 18.67 - 18.68 - <para id="x_d8">However, luck is with me&emdash;I've caught my error 18.69 - before I pushed the changeset. I use the <command 18.70 - role="hg-cmd">hg rollback</command> command, and Mercurial 18.71 - makes that last changeset vanish.</para> 18.72 - 18.73 - &interaction.rollback.rollback; 18.74 - 18.75 - <para id="x_d9">Notice that the changeset is no longer present in the 18.76 - repository's history, and the working directory once again 18.77 - thinks that the file <filename>a</filename> is modified. The 18.78 - commit and rollback have left the working directory exactly as 18.79 - it was prior to the commit; the changeset has been completely 18.80 - erased. I can now safely <command role="hg-cmd">hg 18.81 - add</command> the file <filename>b</filename>, and rerun my 18.82 - commit.</para> 18.83 - 18.84 - &interaction.rollback.add; 18.85 - 18.86 - </sect2> 18.87 - <sect2> 18.88 - <title>The erroneous pull</title> 18.89 - 18.90 - <para id="x_da">It's common practice with Mercurial to maintain separate 18.91 - development branches of a project in different repositories. 18.92 - Your development team might have one shared repository for 18.93 - your project's <quote>0.9</quote> release, and another, 18.94 - containing different changes, for the <quote>1.0</quote> 18.95 - release.</para> 18.96 - 18.97 - <para id="x_db">Given this, you can imagine that the consequences could be 18.98 - messy if you had a local <quote>0.9</quote> repository, and 18.99 - accidentally pulled changes from the shared <quote>1.0</quote> 18.100 - repository into it. At worst, you could be paying 18.101 - insufficient attention, and push those changes into the shared 18.102 - <quote>0.9</quote> tree, confusing your entire team (but don't 18.103 - worry, we'll return to this horror scenario later). However, 18.104 - it's more likely that you'll notice immediately, because 18.105 - Mercurial will display the URL it's pulling from, or you will 18.106 - see it pull a suspiciously large number of changes into the 18.107 - repository.</para> 18.108 - 18.109 - <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command 18.110 - will work nicely to expunge all of the changesets that you 18.111 - just pulled. Mercurial groups all changes from one <command 18.112 - role="hg-cmd">hg pull</command> into a single transaction, 18.113 - so one <command role="hg-cmd">hg rollback</command> is all you 18.114 - need to undo this mistake.</para> 18.115 - 18.116 - </sect2> 18.117 - <sect2 id="sec:undo:rollback-after-push"> 18.118 - <title>Rolling back is useless once you've pushed</title> 18.119 - 18.120 - <para id="x_dd">The value of the <command role="hg-cmd">hg 18.121 - rollback</command> command drops to zero once you've pushed 18.122 - your changes to another repository. Rolling back a change 18.123 - makes it disappear entirely, but <emphasis>only</emphasis> in 18.124 - the repository in which you perform the <command 18.125 - role="hg-cmd">hg rollback</command>. Because a rollback 18.126 - eliminates history, there's no way for the disappearance of a 18.127 - change to propagate between repositories.</para> 18.128 - 18.129 - <para id="x_de">If you've pushed a change to another 18.130 - repository&emdash;particularly if it's a shared 18.131 - repository&emdash;it has essentially <quote>escaped into the 18.132 - wild,</quote> and you'll have to recover from your mistake 18.133 - in a different way. If you push a changeset somewhere, then 18.134 - roll it back, then pull from the repository you pushed to, the 18.135 - changeset you thought you'd gotten rid of will simply reappear 18.136 - in your repository.</para> 18.137 - 18.138 - <para id="x_df">(If you absolutely know for sure that the change 18.139 - you want to roll back is the most recent change in the 18.140 - repository that you pushed to, <emphasis>and</emphasis> you 18.141 - know that nobody else could have pulled it from that 18.142 - repository, you can roll back the changeset there, too, but 18.143 - you really should not expect this to work reliably. Sooner or 18.144 - later a change really will make it into a repository that you 18.145 - don't directly control (or have forgotten about), and come 18.146 - back to bite you.)</para> 18.147 - 18.148 - </sect2> 18.149 - <sect2> 18.150 - <title>You can only roll back once</title> 18.151 - 18.152 - <para id="x_e0">Mercurial stores exactly one transaction in its 18.153 - transaction log; that transaction is the most recent one that 18.154 - occurred in the repository. This means that you can only roll 18.155 - back one transaction. If you expect to be able to roll back 18.156 - one transaction, then its predecessor, this is not the 18.157 - behavior you will get.</para> 18.158 - 18.159 - &interaction.rollback.twice; 18.160 - 18.161 - <para id="x_e1">Once you've rolled back one transaction in a repository, 18.162 - you can't roll back again in that repository until you perform 18.163 - another commit or pull.</para> 18.164 - 18.165 - </sect2> 18.166 - </sect1> 18.167 - <sect1> 18.168 - <title>Reverting the mistaken change</title> 18.169 - 18.170 - <para id="x_e2">If you make a modification to a file, and decide that you 18.171 - really didn't want to change the file at all, and you haven't 18.172 - yet committed your changes, the <command role="hg-cmd">hg 18.173 - revert</command> command is the one you'll need. It looks at 18.174 - the changeset that's the parent of the working directory, and 18.175 - restores the contents of the file to their state as of that 18.176 - changeset. (That's a long-winded way of saying that, in the 18.177 - normal case, it undoes your modifications.)</para> 18.178 - 18.179 - <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg 18.180 - revert</command> command works with yet another small example. 18.181 - We'll begin by modifying a file that Mercurial is already 18.182 - tracking.</para> 18.183 - 18.184 - &interaction.daily.revert.modify; 18.185 - 18.186 - <para id="x_e4">If we don't 18.187 - want that change, we can simply <command role="hg-cmd">hg 18.188 - revert</command> the file.</para> 18.189 - 18.190 - &interaction.daily.revert.unmodify; 18.191 - 18.192 - <para id="x_e5">The <command role="hg-cmd">hg revert</command> command 18.193 - provides us with an extra degree of safety by saving our 18.194 - modified file with a <filename>.orig</filename> 18.195 - extension.</para> 18.196 - 18.197 - &interaction.daily.revert.status; 18.198 - 18.199 - <tip> 18.200 - <title>Be careful with <filename>.orig</filename> files</title> 18.201 - 18.202 - <para id="x_6b8">It's extremely unlikely that you are either using 18.203 - Mercurial to manage files with <filename>.orig</filename> 18.204 - extensions or that you even care about the contents of such 18.205 - files. Just in case, though, it's useful to remember that 18.206 - <command role="hg-cmd">hg revert</command> will 18.207 - unconditionally overwrite an existing file with a 18.208 - <filename>.orig</filename> extension. For instance, if you 18.209 - already have a file named <filename>foo.orig</filename> when 18.210 - you revert <filename>foo</filename>, the contents of 18.211 - <filename>foo.orig</filename> will be clobbered.</para> 18.212 - </tip> 18.213 - 18.214 - <para id="x_e6">Here is a summary of the cases that the <command 18.215 - role="hg-cmd">hg revert</command> command can deal with. We 18.216 - will describe each of these in more detail in the section that 18.217 - follows.</para> 18.218 - <itemizedlist> 18.219 - <listitem><para id="x_e7">If you modify a file, it will restore the file 18.220 - to its unmodified state.</para> 18.221 - </listitem> 18.222 - <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a 18.223 - file, it will undo the <quote>added</quote> state of the 18.224 - file, but leave the file itself untouched.</para> 18.225 - </listitem> 18.226 - <listitem><para id="x_e9">If you delete a file without telling Mercurial, 18.227 - it will restore the file to its unmodified contents.</para> 18.228 - </listitem> 18.229 - <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg 18.230 - remove</command> command to remove a file, it will undo 18.231 - the <quote>removed</quote> state of the file, and restore 18.232 - the file to its unmodified contents.</para> 18.233 - </listitem></itemizedlist> 18.234 - 18.235 - <sect2 id="sec:undo:mgmt"> 18.236 - <title>File management errors</title> 18.237 - 18.238 - <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is 18.239 - useful for more than just modified files. It lets you reverse 18.240 - the results of all of Mercurial's file management 18.241 - commands&emdash;<command role="hg-cmd">hg add</command>, 18.242 - <command role="hg-cmd">hg remove</command>, and so on.</para> 18.243 - 18.244 - <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file, 18.245 - then decide that in fact you don't want Mercurial to track it, 18.246 - use <command role="hg-cmd">hg revert</command> to undo the 18.247 - add. Don't worry; Mercurial will not modify the file in any 18.248 - way. It will just <quote>unmark</quote> the file.</para> 18.249 - 18.250 - &interaction.daily.revert.add; 18.251 - 18.252 - <para id="x_ed">Similarly, if you ask Mercurial to <command 18.253 - role="hg-cmd">hg remove</command> a file, you can use 18.254 - <command role="hg-cmd">hg revert</command> to restore it to 18.255 - the contents it had as of the parent of the working directory. 18.256 - &interaction.daily.revert.remove; This works just as 18.257 - well for a file that you deleted by hand, without telling 18.258 - Mercurial (recall that in Mercurial terminology, this kind of 18.259 - file is called <quote>missing</quote>).</para> 18.260 - 18.261 - &interaction.daily.revert.missing; 18.262 - 18.263 - <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>, 18.264 - the copied-to file remains in your working directory 18.265 - afterwards, untracked. Since a copy doesn't affect the 18.266 - copied-from file in any way, Mercurial doesn't do anything 18.267 - with the copied-from file.</para> 18.268 - 18.269 - &interaction.daily.revert.copy; 18.270 - </sect2> 18.271 - </sect1> 18.272 - 18.273 - <sect1> 18.274 - <title>Dealing with committed changes</title> 18.275 - 18.276 - <para id="x_f5">Consider a case where you have committed a change 18.277 - <emphasis>a</emphasis>, and another change 18.278 - <emphasis>b</emphasis> on top of it; you then realise that 18.279 - change <emphasis>a</emphasis> was incorrect. Mercurial lets you 18.280 - <quote>back out</quote> an entire changeset automatically, and 18.281 - building blocks that let you reverse part of a changeset by 18.282 - hand.</para> 18.283 - 18.284 - <para id="x_f6">Before you read this section, here's something to 18.285 - keep in mind: the <command role="hg-cmd">hg backout</command> 18.286 - command undoes the effect of a change by 18.287 - <emphasis>adding</emphasis> to your repository's history, not by 18.288 - modifying or erasing it. It's the right tool to use if you're 18.289 - fixing bugs, but not if you're trying to undo some change that 18.290 - has catastrophic consequences. To deal with those, see 18.291 - <xref linkend="sec:undo:aaaiiieee"/>.</para> 18.292 - 18.293 - <sect2> 18.294 - <title>Backing out a changeset</title> 18.295 - 18.296 - <para id="x_f7">The <command role="hg-cmd">hg backout</command> command 18.297 - lets you <quote>undo</quote> the effects of an entire 18.298 - changeset in an automated fashion. Because Mercurial's 18.299 - history is immutable, this command <emphasis>does 18.300 - not</emphasis> get rid of the changeset you want to undo. 18.301 - Instead, it creates a new changeset that 18.302 - <emphasis>reverses</emphasis> the effect of the to-be-undone 18.303 - changeset.</para> 18.304 - 18.305 - <para id="x_f8">The operation of the <command role="hg-cmd">hg 18.306 - backout</command> command is a little intricate, so let's 18.307 - illustrate it with some examples. First, we'll create a 18.308 - repository with some simple changes.</para> 18.309 - 18.310 - &interaction.backout.init; 18.311 - 18.312 - <para id="x_f9">The <command role="hg-cmd">hg backout</command> command 18.313 - takes a single changeset ID as its argument; this is the 18.314 - changeset to back out. Normally, <command role="hg-cmd">hg 18.315 - backout</command> will drop you into a text editor to write 18.316 - a commit message, so you can record why you're backing the 18.317 - change out. In this example, we provide a commit message on 18.318 - the command line using the <option 18.319 - role="hg-opt-backout">-m</option> option.</para> 18.320 - 18.321 - </sect2> 18.322 - <sect2> 18.323 - <title>Backing out the tip changeset</title> 18.324 - 18.325 - <para id="x_fa">We're going to start by backing out the last changeset we 18.326 - committed.</para> 18.327 - 18.328 - &interaction.backout.simple; 18.329 - 18.330 - <para id="x_fb">You can see that the second line from 18.331 - <filename>myfile</filename> is no longer present. Taking a 18.332 - look at the output of <command role="hg-cmd">hg log</command> 18.333 - gives us an idea of what the <command role="hg-cmd">hg 18.334 - backout</command> command has done. 18.335 - &interaction.backout.simple.log; Notice that the new changeset 18.336 - that <command role="hg-cmd">hg backout</command> has created 18.337 - is a child of the changeset we backed out. It's easier to see 18.338 - this in <xref linkend="fig:undo:backout"/>, which presents a 18.339 - graphical view of the change history. As you can see, the 18.340 - history is nice and linear.</para> 18.341 - 18.342 - <figure id="fig:undo:backout"> 18.343 - <title>Backing out a change using the <command 18.344 - role="hg-cmd">hg backout</command> command</title> 18.345 - <mediaobject> 18.346 - <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject> 18.347 - <textobject><phrase>XXX add text</phrase></textobject> 18.348 - </mediaobject> 18.349 - </figure> 18.350 - 18.351 - </sect2> 18.352 - <sect2> 18.353 - <title>Backing out a non-tip change</title> 18.354 - 18.355 - <para id="x_fd">If you want to back out a change other than the last one 18.356 - you committed, pass the <option 18.357 - role="hg-opt-backout">--merge</option> option to the 18.358 - <command role="hg-cmd">hg backout</command> command.</para> 18.359 - 18.360 - &interaction.backout.non-tip.clone; 18.361 - 18.362 - <para id="x_fe">This makes backing out any changeset a 18.363 - <quote>one-shot</quote> operation that's usually simple and 18.364 - fast.</para> 18.365 - 18.366 - &interaction.backout.non-tip.backout; 18.367 - 18.368 - <para id="x_ff">If you take a look at the contents of 18.369 - <filename>myfile</filename> after the backout finishes, you'll 18.370 - see that the first and third changes are present, but not the 18.371 - second.</para> 18.372 - 18.373 - &interaction.backout.non-tip.cat; 18.374 - 18.375 - <para id="x_100">As the graphical history in <xref 18.376 - linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial 18.377 - still commits one change in this kind of situation (the 18.378 - box-shaped node is the ones that Mercurial commits 18.379 - automatically), but the revision graph now looks different. 18.380 - Before Mercurial begins the backout process, it first 18.381 - remembers what the current parent of the working directory is. 18.382 - It then backs out the target changeset, and commits that as a 18.383 - changeset. Finally, it merges back to the previous parent of 18.384 - the working directory, but notice that it <emphasis>does not 18.385 - commit</emphasis> the result of the merge. The repository 18.386 - now contains two heads, and the working directory is in a 18.387 - merge state.</para> 18.388 - 18.389 - <figure id="fig:undo:backout-non-tip"> 18.390 - <title>Automated backout of a non-tip change using the 18.391 - <command role="hg-cmd">hg backout</command> command</title> 18.392 - <mediaobject> 18.393 - <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject> 18.394 - <textobject><phrase>XXX add text</phrase></textobject> 18.395 - </mediaobject> 18.396 - </figure> 18.397 - 18.398 - <para id="x_103">The result is that you end up <quote>back where you 18.399 - were</quote>, only with some extra history that undoes the 18.400 - effect of the changeset you wanted to back out.</para> 18.401 - 18.402 - <para id="x_6b9">You might wonder why Mercurial does not commit the result 18.403 - of the merge that it performed. The reason lies in Mercurial 18.404 - behaving conservatively: a merge naturally has more scope for 18.405 - error than simply undoing the effect of the tip changeset, 18.406 - so your work will be safest if you first inspect (and test!) 18.407 - the result of the merge, <emphasis>then</emphasis> commit 18.408 - it.</para> 18.409 - 18.410 - <sect3> 18.411 - <title>Always use the <option 18.412 - role="hg-opt-backout">--merge</option> option</title> 18.413 - 18.414 - <para id="x_104">In fact, since the <option 18.415 - role="hg-opt-backout">--merge</option> option will do the 18.416 - <quote>right thing</quote> whether or not the changeset 18.417 - you're backing out is the tip (i.e. it won't try to merge if 18.418 - it's backing out the tip, since there's no need), you should 18.419 - <emphasis>always</emphasis> use this option when you run the 18.420 - <command role="hg-cmd">hg backout</command> command.</para> 18.421 - 18.422 - </sect3> 18.423 - </sect2> 18.424 - <sect2> 18.425 - <title>Gaining more control of the backout process</title> 18.426 - 18.427 - <para id="x_105">While I've recommended that you always use the <option 18.428 - role="hg-opt-backout">--merge</option> option when backing 18.429 - out a change, the <command role="hg-cmd">hg backout</command> 18.430 - command lets you decide how to merge a backout changeset. 18.431 - Taking control of the backout process by hand is something you 18.432 - will rarely need to do, but it can be useful to understand 18.433 - what the <command role="hg-cmd">hg backout</command> command 18.434 - is doing for you automatically. To illustrate this, let's 18.435 - clone our first repository, but omit the backout change that 18.436 - it contains.</para> 18.437 - 18.438 - &interaction.backout.manual.clone; 18.439 - 18.440 - <para id="x_106">As with our 18.441 - earlier example, We'll commit a third changeset, then back out 18.442 - its parent, and see what happens.</para> 18.443 - 18.444 - &interaction.backout.manual.backout; 18.445 - 18.446 - <para id="x_107">Our new changeset is again a descendant of the changeset 18.447 - we backout out; it's thus a new head, <emphasis>not</emphasis> 18.448 - a descendant of the changeset that was the tip. The <command 18.449 - role="hg-cmd">hg backout</command> command was quite 18.450 - explicit in telling us this.</para> 18.451 - 18.452 - &interaction.backout.manual.log; 18.453 - 18.454 - <para id="x_108">Again, it's easier to see what has happened by looking at 18.455 - a graph of the revision history, in <xref 18.456 - linkend="fig:undo:backout-manual"/>. This makes it clear 18.457 - that when we use <command role="hg-cmd">hg backout</command> 18.458 - to back out a change other than the tip, Mercurial adds a new 18.459 - head to the repository (the change it committed is 18.460 - box-shaped).</para> 18.461 - 18.462 - <figure id="fig:undo:backout-manual"> 18.463 - <title>Backing out a change using the <command 18.464 - role="hg-cmd">hg backout</command> command</title> 18.465 - <mediaobject> 18.466 - <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject> 18.467 - <textobject><phrase>XXX add text</phrase></textobject> 18.468 - </mediaobject> 18.469 - </figure> 18.470 - 18.471 - <para id="x_10a">After the <command role="hg-cmd">hg backout</command> 18.472 - command has completed, it leaves the new 18.473 - <quote>backout</quote> changeset as the parent of the working 18.474 - directory.</para> 18.475 - 18.476 - &interaction.backout.manual.parents; 18.477 - 18.478 - <para id="x_10b">Now we have two isolated sets of changes.</para> 18.479 - 18.480 - &interaction.backout.manual.heads; 18.481 - 18.482 - <para id="x_10c">Let's think about what we expect to see as the contents of 18.483 - <filename>myfile</filename> now. The first change should be 18.484 - present, because we've never backed it out. The second change 18.485 - should be missing, as that's the change we backed out. Since 18.486 - the history graph shows the third change as a separate head, 18.487 - we <emphasis>don't</emphasis> expect to see the third change 18.488 - present in <filename>myfile</filename>.</para> 18.489 - 18.490 - &interaction.backout.manual.cat; 18.491 - 18.492 - <para id="x_10d">To get the third change back into the file, we just do a 18.493 - normal merge of our two heads.</para> 18.494 - 18.495 - &interaction.backout.manual.merge; 18.496 - 18.497 - <para id="x_10e">Afterwards, the graphical history of our 18.498 - repository looks like 18.499 - <xref linkend="fig:undo:backout-manual-merge"/>.</para> 18.500 - 18.501 - <figure id="fig:undo:backout-manual-merge"> 18.502 - <title>Manually merging a backout change</title> 18.503 - <mediaobject> 18.504 - <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject> 18.505 - <textobject><phrase>XXX add text</phrase></textobject> 18.506 - </mediaobject> 18.507 - </figure> 18.508 - 18.509 - </sect2> 18.510 - <sect2> 18.511 - <title>Why <command role="hg-cmd">hg backout</command> works as 18.512 - it does</title> 18.513 - 18.514 - <para id="x_110">Here's a brief description of how the <command 18.515 - role="hg-cmd">hg backout</command> command works.</para> 18.516 - <orderedlist> 18.517 - <listitem><para id="x_111">It ensures that the working directory is 18.518 - <quote>clean</quote>, i.e. that the output of <command 18.519 - role="hg-cmd">hg status</command> would be empty.</para> 18.520 - </listitem> 18.521 - <listitem><para id="x_112">It remembers the current parent of the working 18.522 - directory. Let's call this changeset 18.523 - <literal>orig</literal>.</para> 18.524 - </listitem> 18.525 - <listitem><para id="x_113">It does the equivalent of a <command 18.526 - role="hg-cmd">hg update</command> to sync the working 18.527 - directory to the changeset you want to back out. Let's 18.528 - call this changeset <literal>backout</literal>.</para> 18.529 - </listitem> 18.530 - <listitem><para id="x_114">It finds the parent of that changeset. Let's 18.531 - call that changeset <literal>parent</literal>.</para> 18.532 - </listitem> 18.533 - <listitem><para id="x_115">For each file that the 18.534 - <literal>backout</literal> changeset affected, it does the 18.535 - equivalent of a <command role="hg-cmd">hg revert -r 18.536 - parent</command> on that file, to restore it to the 18.537 - contents it had before that changeset was 18.538 - committed.</para> 18.539 - </listitem> 18.540 - <listitem><para id="x_116">It commits the result as a new changeset. 18.541 - This changeset has <literal>backout</literal> as its 18.542 - parent.</para> 18.543 - </listitem> 18.544 - <listitem><para id="x_117">If you specify <option 18.545 - role="hg-opt-backout">--merge</option> on the command 18.546 - line, it merges with <literal>orig</literal>, and commits 18.547 - the result of the merge.</para> 18.548 - </listitem></orderedlist> 18.549 - 18.550 - <para id="x_118">An alternative way to implement the <command 18.551 - role="hg-cmd">hg backout</command> command would be to 18.552 - <command role="hg-cmd">hg export</command> the 18.553 - to-be-backed-out changeset as a diff, then use the <option 18.554 - role="cmd-opt-patch">--reverse</option> option to the 18.555 - <command>patch</command> command to reverse the effect of the 18.556 - change without fiddling with the working directory. This 18.557 - sounds much simpler, but it would not work nearly as 18.558 - well.</para> 18.559 - 18.560 - <para id="x_119">The reason that <command role="hg-cmd">hg 18.561 - backout</command> does an update, a commit, a merge, and 18.562 - another commit is to give the merge machinery the best chance 18.563 - to do a good job when dealing with all the changes 18.564 - <emphasis>between</emphasis> the change you're backing out and 18.565 - the current tip.</para> 18.566 - 18.567 - <para id="x_11a">If you're backing out a changeset that's 100 revisions 18.568 - back in your project's history, the chances that the 18.569 - <command>patch</command> command will be able to apply a 18.570 - reverse diff cleanly are not good, because intervening changes 18.571 - are likely to have <quote>broken the context</quote> that 18.572 - <command>patch</command> uses to determine whether it can 18.573 - apply a patch (if this sounds like gibberish, see <xref 18.574 - linkend="sec:mq:patch"/> for a 18.575 - discussion of the <command>patch</command> command). Also, 18.576 - Mercurial's merge machinery will handle files and directories 18.577 - being renamed, permission changes, and modifications to binary 18.578 - files, none of which <command>patch</command> can deal 18.579 - with.</para> 18.580 - 18.581 - </sect2> 18.582 - </sect1> 18.583 - <sect1 id="sec:undo:aaaiiieee"> 18.584 - <title>Changes that should never have been</title> 18.585 - 18.586 - <para id="x_11b">Most of the time, the <command role="hg-cmd">hg 18.587 - backout</command> command is exactly what you need if you want 18.588 - to undo the effects of a change. It leaves a permanent record 18.589 - of exactly what you did, both when committing the original 18.590 - changeset and when you cleaned up after it.</para> 18.591 - 18.592 - <para id="x_11c">On rare occasions, though, you may find that you've 18.593 - committed a change that really should not be present in the 18.594 - repository at all. For example, it would be very unusual, and 18.595 - usually considered a mistake, to commit a software project's 18.596 - object files as well as its source files. Object files have 18.597 - almost no intrinsic value, and they're <emphasis>big</emphasis>, 18.598 - so they increase the size of the repository and the amount of 18.599 - time it takes to clone or pull changes.</para> 18.600 - 18.601 - <para id="x_11d">Before I discuss the options that you have if you commit a 18.602 - <quote>brown paper bag</quote> change (the kind that's so bad 18.603 - that you want to pull a brown paper bag over your head), let me 18.604 - first discuss some approaches that probably won't work.</para> 18.605 - 18.606 - <para id="x_11e">Since Mercurial treats history as 18.607 - accumulative&emdash;every change builds on top of all changes 18.608 - that preceded it&emdash;you generally can't just make disastrous 18.609 - changes disappear. The one exception is when you've just 18.610 - committed a change, and it hasn't been pushed or pulled into 18.611 - another repository. That's when you can safely use the <command 18.612 - role="hg-cmd">hg rollback</command> command, as I detailed in 18.613 - <xref linkend="sec:undo:rollback"/>.</para> 18.614 - 18.615 - <para id="x_11f">After you've pushed a bad change to another repository, you 18.616 - <emphasis>could</emphasis> still use <command role="hg-cmd">hg 18.617 - rollback</command> to make your local copy of the change 18.618 - disappear, but it won't have the consequences you want. The 18.619 - change will still be present in the remote repository, so it 18.620 - will reappear in your local repository the next time you 18.621 - pull.</para> 18.622 - 18.623 - <para id="x_120">If a situation like this arises, and you know which 18.624 - repositories your bad change has propagated into, you can 18.625 - <emphasis>try</emphasis> to get rid of the change from 18.626 - <emphasis>every</emphasis> one of those repositories. This is, 18.627 - of course, not a satisfactory solution: if you miss even a 18.628 - single repository while you're expunging, the change is still 18.629 - <quote>in the wild</quote>, and could propagate further.</para> 18.630 - 18.631 - <para id="x_121">If you've committed one or more changes 18.632 - <emphasis>after</emphasis> the change that you'd like to see 18.633 - disappear, your options are further reduced. Mercurial doesn't 18.634 - provide a way to <quote>punch a hole</quote> in history, leaving 18.635 - changesets intact.</para> 18.636 - 18.637 - <sect2> 18.638 - <title>Backing out a merge</title> 18.639 - 18.640 - <para id="x_6ba">Since merges are often complicated, it is not unheard of 18.641 - for a merge to be mangled badly, but committed erroneously. 18.642 - Mercurial provides an important safeguard against bad merges 18.643 - by refusing to commit unresolved files, but human ingenuity 18.644 - guarantees that it is still possible to mess a merge up and 18.645 - commit it.</para> 18.646 - 18.647 - <para id="x_6bb">Given a bad merge that has been committed, usually the 18.648 - best way to approach it is to simply try to repair the damage 18.649 - by hand. A complete disaster that cannot be easily fixed up 18.650 - by hand ought to be very rare, but the <command 18.651 - role="hg-cmd">hg backout</command> command may help in 18.652 - making the cleanup easier. It offers a <option 18.653 - role="hg-opt-backout">--parent</option> option, which lets 18.654 - you specify which parent to revert to when backing out a 18.655 - merge.</para> 18.656 - 18.657 - <figure id="fig:undo:bad-merge-1"> 18.658 - <title>A bad merge</title> 18.659 - <mediaobject> 18.660 - <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject> 18.661 - <textobject><phrase>XXX add text</phrase></textobject> 18.662 - </mediaobject> 18.663 - </figure> 18.664 - 18.665 - <para id="x_6bc">Suppose we have a revision graph like that in <xref 18.666 - linkend="fig:undo:bad-merge-1"/>. What we'd like is to 18.667 - <emphasis>redo</emphasis> the merge of revisions 2 and 18.668 - 3.</para> 18.669 - 18.670 - <para id="x_6bd">One way to do so would be as follows.</para> 18.671 - 18.672 - <orderedlist> 18.673 - <listitem> 18.674 - <para id="x_6be">Call <command role="hg-cmd">hg backout --rev=4 18.675 - --parent=2</command>. This tells <command 18.676 - role="hg-cmd">hg backout</command> to back out revision 18.677 - 4, which is the bad merge, and to when deciding which 18.678 - revision to prefer, to choose parent 2, one of the parents 18.679 - of the merge. The effect can be seen in <xref 18.680 - linkend="fig:undo:bad-merge-2"/>.</para> 18.681 - <figure id="fig:undo:bad-merge-2"> 18.682 - <title>Backing out the merge, favoring one parent</title> 18.683 - <mediaobject> 18.684 - <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject> 18.685 - <textobject><phrase>XXX add text</phrase></textobject> 18.686 - </mediaobject> 18.687 - </figure> 18.688 - </listitem> 18.689 - 18.690 - <listitem> 18.691 - <para id="x_6bf">Call <command role="hg-cmd">hg backout --rev=4 18.692 - --parent=3</command>. This tells <command 18.693 - role="hg-cmd">hg backout</command> to back out revision 18.694 - 4 again, but this time to choose parent 3, the other 18.695 - parent of the merge. The result is visible in <xref 18.696 - linkend="fig:undo:bad-merge-3"/>, in which the repository 18.697 - now contains three heads.</para> 18.698 - <figure id="fig:undo:bad-merge-3"> 18.699 - <title>Backing out the merge, favoring the other 18.700 - parent</title> 18.701 - <mediaobject> 18.702 - <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject> 18.703 - <textobject><phrase>XXX add text</phrase></textobject> 18.704 - </mediaobject> 18.705 - </figure> 18.706 - </listitem> 18.707 - 18.708 - <listitem> 18.709 - <para id="x_6c0">Redo the bad merge by merging the two backout heads, 18.710 - which reduces the number of heads in the repository to 18.711 - two, as can be seen in <xref 18.712 - linkend="fig:undo:bad-merge-4"/>.</para> 18.713 - <figure id="fig:undo:bad-merge-4"> 18.714 - <title>Merging the backouts</title> 18.715 - <mediaobject> 18.716 - <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject> 18.717 - <textobject><phrase>XXX add text</phrase></textobject> 18.718 - </mediaobject> 18.719 - </figure> 18.720 - </listitem> 18.721 - 18.722 - <listitem> 18.723 - <para id="x_6c1">Merge with the commit that was made after the bad 18.724 - merge, as shown in <xref 18.725 - linkend="fig:undo:bad-merge-5"/>.</para> 18.726 - <figure id="fig:undo:bad-merge-5"> 18.727 - <title>Merging the backouts</title> 18.728 - <mediaobject> 18.729 - <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject> 18.730 - <textobject><phrase>XXX add text</phrase></textobject> 18.731 - </mediaobject> 18.732 - </figure> 18.733 - </listitem> 18.734 - </orderedlist> 18.735 - </sect2> 18.736 - 18.737 - <sect2> 18.738 - <title>Protect yourself from <quote>escaped</quote> 18.739 - changes</title> 18.740 - 18.741 - <para id="x_123">If you've committed some changes to your local repository 18.742 - and they've been pushed or pulled somewhere else, this isn't 18.743 - necessarily a disaster. You can protect yourself ahead of 18.744 - time against some classes of bad changeset. This is 18.745 - particularly easy if your team usually pulls changes from a 18.746 - central repository.</para> 18.747 - 18.748 - <para id="x_124">By configuring some hooks on that repository to validate 18.749 - incoming changesets (see chapter <xref linkend="chap:hook"/>), 18.750 - you can 18.751 - automatically prevent some kinds of bad changeset from being 18.752 - pushed to the central repository at all. With such a 18.753 - configuration in place, some kinds of bad changeset will 18.754 - naturally tend to <quote>die out</quote> because they can't 18.755 - propagate into the central repository. Better yet, this 18.756 - happens without any need for explicit intervention.</para> 18.757 - 18.758 - <para id="x_125">For instance, an incoming change hook that 18.759 - verifies that a changeset will actually compile can prevent 18.760 - people from inadvertently <quote>breaking the 18.761 - build</quote>.</para> 18.762 - </sect2> 18.763 - 18.764 - <sect2> 18.765 - <title>What to do about sensitive changes that escape</title> 18.766 - 18.767 - <para id="x_6c2">Even a carefully run project can suffer an unfortunate 18.768 - event such as the committing and uncontrolled propagation of a 18.769 - file that contains important passwords.</para> 18.770 - 18.771 - <para id="x_6c3">If something like this happens to you, and the information 18.772 - that gets accidentally propagated is truly sensitive, your 18.773 - first step should be to mitigate the effect of the leak 18.774 - without trying to control the leak itself. If you are not 100% 18.775 - certain that you know exactly who could have seen the changes, 18.776 - you should immediately change passwords, cancel credit cards, 18.777 - or find some other way to make sure that the information that 18.778 - has leaked is no longer useful. In other words, assume that 18.779 - the change has propagated far and wide, and that there's 18.780 - nothing more you can do.</para> 18.781 - 18.782 - <para id="x_6c4">You might hope that there would be mechanisms you could 18.783 - use to either figure out who has seen a change or to erase the 18.784 - change permanently everywhere, but there are good reasons why 18.785 - these are not possible.</para> 18.786 - 18.787 - <para id="x_6c5">Mercurial does not provide an audit trail of who has 18.788 - pulled changes from a repository, because it is usually either 18.789 - impossible to record such information or trivial to spoof it. 18.790 - In a multi-user or networked environment, you should thus be 18.791 - extremely skeptical of yourself if you think that you have 18.792 - identified every place that a sensitive changeset has 18.793 - propagated to. Don't forget that people can and will send 18.794 - bundles by email, have their backup software save data 18.795 - offsite, carry repositories on USB sticks, and find other 18.796 - completely innocent ways to confound your attempts to track 18.797 - down every copy of a problematic change.</para> 18.798 - 18.799 - <para id="x_6c6">Mercurial also does not provide a way to make a file or 18.800 - changeset completely disappear from history, because there is 18.801 - no way to enforce its disappearance; someone could easily 18.802 - modify their copy of Mercurial to ignore such directives. In 18.803 - addition, even if Mercurial provided such a capability, 18.804 - someone who simply hadn't pulled a <quote>make this file 18.805 - disappear</quote> changeset wouldn't be affected by it, nor 18.806 - would web crawlers visiting at the wrong time, disk backups, 18.807 - or other mechanisms. Indeed, no distributed revision control 18.808 - system can make data reliably vanish. Providing the illusion 18.809 - of such control could easily give a false sense of security, 18.810 - and be worse than not providing it at all.</para> 18.811 - </sect2> 18.812 - </sect1> 18.813 - 18.814 - <sect1 id="sec:undo:bisect"> 18.815 - <title>Finding the source of a bug</title> 18.816 - 18.817 - <para id="x_126">While it's all very well to be able to back out a changeset 18.818 - that introduced a bug, this requires that you know which 18.819 - changeset to back out. Mercurial provides an invaluable 18.820 - command, called <command role="hg-cmd">hg bisect</command>, that 18.821 - helps you to automate this process and accomplish it very 18.822 - efficiently.</para> 18.823 - 18.824 - <para id="x_127">The idea behind the <command role="hg-cmd">hg 18.825 - bisect</command> command is that a changeset has introduced 18.826 - some change of behavior that you can identify with a simple 18.827 - pass/fail test. You don't know which piece of code introduced the 18.828 - change, but you know how to test for the presence of the bug. 18.829 - The <command role="hg-cmd">hg bisect</command> command uses your 18.830 - test to direct its search for the changeset that introduced the 18.831 - code that caused the bug.</para> 18.832 - 18.833 - <para id="x_128">Here are a few scenarios to help you understand how you 18.834 - might apply this command.</para> 18.835 - <itemizedlist> 18.836 - <listitem><para id="x_129">The most recent version of your software has a 18.837 - bug that you remember wasn't present a few weeks ago, but 18.838 - you don't know when it was introduced. Here, your binary 18.839 - test checks for the presence of that bug.</para> 18.840 - </listitem> 18.841 - <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to 18.842 - close the entry in your team's bug database. The bug 18.843 - database requires a changeset ID when you close an entry, 18.844 - but you don't remember which changeset you fixed the bug in. 18.845 - Once again, your binary test checks for the presence of the 18.846 - bug.</para> 18.847 - </listitem> 18.848 - <listitem><para id="x_12b">Your software works correctly, but runs 15% 18.849 - slower than the last time you measured it. You want to know 18.850 - which changeset introduced the performance regression. In 18.851 - this case, your binary test measures the performance of your 18.852 - software, to see whether it's <quote>fast</quote> or 18.853 - <quote>slow</quote>.</para> 18.854 - </listitem> 18.855 - <listitem><para id="x_12c">The sizes of the components of your project that 18.856 - you ship exploded recently, and you suspect that something 18.857 - changed in the way you build your project.</para> 18.858 - </listitem></itemizedlist> 18.859 - 18.860 - <para id="x_12d">From these examples, it should be clear that the <command 18.861 - role="hg-cmd">hg bisect</command> command is not useful only 18.862 - for finding the sources of bugs. You can use it to find any 18.863 - <quote>emergent property</quote> of a repository (anything that 18.864 - you can't find from a simple text search of the files in the 18.865 - tree) for which you can write a binary test.</para> 18.866 - 18.867 - <para id="x_12e">We'll introduce a little bit of terminology here, just to 18.868 - make it clear which parts of the search process are your 18.869 - responsibility, and which are Mercurial's. A 18.870 - <emphasis>test</emphasis> is something that 18.871 - <emphasis>you</emphasis> run when <command role="hg-cmd">hg 18.872 - bisect</command> chooses a changeset. A 18.873 - <emphasis>probe</emphasis> is what <command role="hg-cmd">hg 18.874 - bisect</command> runs to tell whether a revision is good. 18.875 - Finally, we'll use the word <quote>bisect</quote>, as both a 18.876 - noun and a verb, to stand in for the phrase <quote>search using 18.877 - the <command role="hg-cmd">hg bisect</command> 18.878 - command</quote>.</para> 18.879 - 18.880 - <para id="x_12f">One simple way to automate the searching process would be 18.881 - simply to probe every changeset. However, this scales poorly. 18.882 - If it took ten minutes to test a single changeset, and you had 18.883 - 10,000 changesets in your repository, the exhaustive approach 18.884 - would take on average 35 <emphasis>days</emphasis> to find the 18.885 - changeset that introduced a bug. Even if you knew that the bug 18.886 - was introduced by one of the last 500 changesets, and limited 18.887 - your search to those, you'd still be looking at over 40 hours to 18.888 - find the changeset that introduced your bug.</para> 18.889 - 18.890 - <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command 18.891 - does is use its knowledge of the <quote>shape</quote> of your 18.892 - project's revision history to perform a search in time 18.893 - proportional to the <emphasis>logarithm</emphasis> of the number 18.894 - of changesets to check (the kind of search it performs is called 18.895 - a dichotomic search). With this approach, searching through 18.896 - 10,000 changesets will take less than three hours, even at ten 18.897 - minutes per test (the search will require about 14 tests). 18.898 - Limit your search to the last hundred changesets, and it will 18.899 - take only about an hour (roughly seven tests).</para> 18.900 - 18.901 - <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is 18.902 - aware of the <quote>branchy</quote> nature of a Mercurial 18.903 - project's revision history, so it has no problems dealing with 18.904 - branches, merges, or multiple heads in a repository. It can 18.905 - prune entire branches of history with a single probe, which is 18.906 - how it operates so efficiently.</para> 18.907 - 18.908 - <sect2> 18.909 - <title>Using the <command role="hg-cmd">hg bisect</command> 18.910 - command</title> 18.911 - 18.912 - <para id="x_132">Here's an example of <command role="hg-cmd">hg 18.913 - bisect</command> in action.</para> 18.914 - 18.915 - <note> 18.916 - <para id="x_133"> In versions 0.9.5 and earlier of Mercurial, <command 18.917 - role="hg-cmd">hg bisect</command> was not a core command: 18.918 - it was distributed with Mercurial as an extension. This 18.919 - section describes the built-in command, not the old 18.920 - extension.</para> 18.921 - </note> 18.922 - 18.923 - <para id="x_134">Now let's create a repository, so that we can try out the 18.924 - <command role="hg-cmd">hg bisect</command> command in 18.925 - isolation.</para> 18.926 - 18.927 - &interaction.bisect.init; 18.928 - 18.929 - <para id="x_135">We'll simulate a project that has a bug in it in a 18.930 - simple-minded way: create trivial changes in a loop, and 18.931 - nominate one specific change that will have the 18.932 - <quote>bug</quote>. This loop creates 35 changesets, each 18.933 - adding a single file to the repository. We'll represent our 18.934 - <quote>bug</quote> with a file that contains the text <quote>i 18.935 - have a gub</quote>.</para> 18.936 - 18.937 - &interaction.bisect.commits; 18.938 - 18.939 - <para id="x_136">The next thing that we'd like to do is figure out how to 18.940 - use the <command role="hg-cmd">hg bisect</command> command. 18.941 - We can use Mercurial's normal built-in help mechanism for 18.942 - this.</para> 18.943 - 18.944 - &interaction.bisect.help; 18.945 - 18.946 - <para id="x_137">The <command role="hg-cmd">hg bisect</command> command 18.947 - works in steps. Each step proceeds as follows.</para> 18.948 - <orderedlist> 18.949 - <listitem><para id="x_138">You run your binary test.</para> 18.950 - <itemizedlist> 18.951 - <listitem><para id="x_139">If the test succeeded, you tell <command 18.952 - role="hg-cmd">hg bisect</command> by running the 18.953 - <command role="hg-cmd">hg bisect --good</command> 18.954 - command.</para> 18.955 - </listitem> 18.956 - <listitem><para id="x_13a">If it failed, run the <command 18.957 - role="hg-cmd">hg bisect --bad</command> 18.958 - command.</para></listitem></itemizedlist> 18.959 - </listitem> 18.960 - <listitem><para id="x_13b">The command uses your information to decide 18.961 - which changeset to test next.</para> 18.962 - </listitem> 18.963 - <listitem><para id="x_13c">It updates the working directory to that 18.964 - changeset, and the process begins again.</para> 18.965 - </listitem></orderedlist> 18.966 - <para id="x_13d">The process ends when <command role="hg-cmd">hg 18.967 - bisect</command> identifies a unique changeset that marks 18.968 - the point where your test transitioned from 18.969 - <quote>succeeding</quote> to <quote>failing</quote>.</para> 18.970 - 18.971 - <para id="x_13e">To start the search, we must run the <command 18.972 - role="hg-cmd">hg bisect --reset</command> command.</para> 18.973 - 18.974 - &interaction.bisect.search.init; 18.975 - 18.976 - <para id="x_13f">In our case, the binary test we use is simple: we check to 18.977 - see if any file in the repository contains the string <quote>i 18.978 - have a gub</quote>. If it does, this changeset contains the 18.979 - change that <quote>caused the bug</quote>. By convention, a 18.980 - changeset that has the property we're searching for is 18.981 - <quote>bad</quote>, while one that doesn't is 18.982 - <quote>good</quote>.</para> 18.983 - 18.984 - <para id="x_140">Most of the time, the revision to which the working 18.985 - directory is synced (usually the tip) already exhibits the 18.986 - problem introduced by the buggy change, so we'll mark it as 18.987 - <quote>bad</quote>.</para> 18.988 - 18.989 - &interaction.bisect.search.bad-init; 18.990 - 18.991 - <para id="x_141">Our next task is to nominate a changeset that we know 18.992 - <emphasis>doesn't</emphasis> have the bug; the <command 18.993 - role="hg-cmd">hg bisect</command> command will 18.994 - <quote>bracket</quote> its search between the first pair of 18.995 - good and bad changesets. In our case, we know that revision 18.996 - 10 didn't have the bug. (I'll have more words about choosing 18.997 - the first <quote>good</quote> changeset later.)</para> 18.998 - 18.999 - &interaction.bisect.search.good-init; 18.1000 - 18.1001 - <para id="x_142">Notice that this command printed some output.</para> 18.1002 - <itemizedlist> 18.1003 - <listitem><para id="x_143">It told us how many changesets it must 18.1004 - consider before it can identify the one that introduced 18.1005 - the bug, and how many tests that will require.</para> 18.1006 - </listitem> 18.1007 - <listitem><para id="x_144">It updated the working directory to the next 18.1008 - changeset to test, and told us which changeset it's 18.1009 - testing.</para> 18.1010 - </listitem></itemizedlist> 18.1011 - 18.1012 - <para id="x_145">We now run our test in the working directory. We use the 18.1013 - <command>grep</command> command to see if our 18.1014 - <quote>bad</quote> file is present in the working directory. 18.1015 - If it is, this revision is bad; if not, this revision is good. 18.1016 - &interaction.bisect.search.step1;</para> 18.1017 - 18.1018 - <para id="x_146">This test looks like a perfect candidate for automation, 18.1019 - so let's turn it into a shell function.</para> 18.1020 - &interaction.bisect.search.mytest; 18.1021 - 18.1022 - <para id="x_147">We can now run an entire test step with a single command, 18.1023 - <literal>mytest</literal>.</para> 18.1024 - 18.1025 - &interaction.bisect.search.step2; 18.1026 - 18.1027 - <para id="x_148">A few more invocations of our canned test step command, 18.1028 - and we're done.</para> 18.1029 - 18.1030 - &interaction.bisect.search.rest; 18.1031 - 18.1032 - <para id="x_149">Even though we had 40 changesets to search through, the 18.1033 - <command role="hg-cmd">hg bisect</command> command let us find 18.1034 - the changeset that introduced our <quote>bug</quote> with only 18.1035 - five tests. Because the number of tests that the <command 18.1036 - role="hg-cmd">hg bisect</command> command performs grows 18.1037 - logarithmically with the number of changesets to search, the 18.1038 - advantage that it has over the <quote>brute force</quote> 18.1039 - search approach increases with every changeset you add.</para> 18.1040 - 18.1041 - </sect2> 18.1042 - <sect2> 18.1043 - <title>Cleaning up after your search</title> 18.1044 - 18.1045 - <para id="x_14a">When you're finished using the <command role="hg-cmd">hg 18.1046 - bisect</command> command in a repository, you can use the 18.1047 - <command role="hg-cmd">hg bisect --reset</command> command to 18.1048 - drop the information it was using to drive your search. The 18.1049 - command doesn't use much space, so it doesn't matter if you 18.1050 - forget to run this command. However, <command 18.1051 - role="hg-cmd">hg bisect</command> won't let you start a new 18.1052 - search in that repository until you do a <command 18.1053 - role="hg-cmd">hg bisect --reset</command>.</para> 18.1054 - 18.1055 - &interaction.bisect.search.reset; 18.1056 - 18.1057 - </sect2> 18.1058 - </sect1> 18.1059 - <sect1> 18.1060 - <title>Tips for finding bugs effectively</title> 18.1061 - 18.1062 - <sect2> 18.1063 - <title>Give consistent input</title> 18.1064 - 18.1065 - <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command 18.1066 - requires that you correctly report the result of every test 18.1067 - you perform. If you tell it that a test failed when it really 18.1068 - succeeded, it <emphasis>might</emphasis> be able to detect the 18.1069 - inconsistency. If it can identify an inconsistency in your 18.1070 - reports, it will tell you that a particular changeset is both 18.1071 - good and bad. However, it can't do this perfectly; it's about 18.1072 - as likely to report the wrong changeset as the source of the 18.1073 - bug.</para> 18.1074 - 18.1075 - </sect2> 18.1076 - <sect2> 18.1077 - <title>Automate as much as possible</title> 18.1078 - 18.1079 - <para id="x_14c">When I started using the <command role="hg-cmd">hg 18.1080 - bisect</command> command, I tried a few times to run my 18.1081 - tests by hand, on the command line. This is an approach that 18.1082 - I, at least, am not suited to. After a few tries, I found 18.1083 - that I was making enough mistakes that I was having to restart 18.1084 - my searches several times before finally getting correct 18.1085 - results.</para> 18.1086 - 18.1087 - <para id="x_14d">My initial problems with driving the <command 18.1088 - role="hg-cmd">hg bisect</command> command by hand occurred 18.1089 - even with simple searches on small repositories; if the 18.1090 - problem you're looking for is more subtle, or the number of 18.1091 - tests that <command role="hg-cmd">hg bisect</command> must 18.1092 - perform increases, the likelihood of operator error ruining 18.1093 - the search is much higher. Once I started automating my 18.1094 - tests, I had much better results.</para> 18.1095 - 18.1096 - <para id="x_14e">The key to automated testing is twofold:</para> 18.1097 - <itemizedlist> 18.1098 - <listitem><para id="x_14f">always test for the same symptom, and</para> 18.1099 - </listitem> 18.1100 - <listitem><para id="x_150">always feed consistent input to the <command 18.1101 - role="hg-cmd">hg bisect</command> command.</para> 18.1102 - </listitem></itemizedlist> 18.1103 - <para id="x_151">In my tutorial example above, the <command>grep</command> 18.1104 - command tests for the symptom, and the <literal>if</literal> 18.1105 - statement takes the result of this check and ensures that we 18.1106 - always feed the same input to the <command role="hg-cmd">hg 18.1107 - bisect</command> command. The <literal>mytest</literal> 18.1108 - function marries these together in a reproducible way, so that 18.1109 - every test is uniform and consistent.</para> 18.1110 - 18.1111 - </sect2> 18.1112 - <sect2> 18.1113 - <title>Check your results</title> 18.1114 - 18.1115 - <para id="x_152">Because the output of a <command role="hg-cmd">hg 18.1116 - bisect</command> search is only as good as the input you 18.1117 - give it, don't take the changeset it reports as the absolute 18.1118 - truth. A simple way to cross-check its report is to manually 18.1119 - run your test at each of the following changesets:</para> 18.1120 - <itemizedlist> 18.1121 - <listitem><para id="x_153">The changeset that it reports as the first bad 18.1122 - revision. Your test should still report this as 18.1123 - bad.</para> 18.1124 - </listitem> 18.1125 - <listitem><para id="x_154">The parent of that changeset (either parent, 18.1126 - if it's a merge). Your test should report this changeset 18.1127 - as good.</para> 18.1128 - </listitem> 18.1129 - <listitem><para id="x_155">A child of that changeset. Your test should 18.1130 - report this changeset as bad.</para> 18.1131 - </listitem></itemizedlist> 18.1132 - 18.1133 - </sect2> 18.1134 - <sect2> 18.1135 - <title>Beware interference between bugs</title> 18.1136 - 18.1137 - <para id="x_156">It's possible that your search for one bug could be 18.1138 - disrupted by the presence of another. For example, let's say 18.1139 - your software crashes at revision 100, and worked correctly at 18.1140 - revision 50. Unknown to you, someone else introduced a 18.1141 - different crashing bug at revision 60, and fixed it at 18.1142 - revision 80. This could distort your results in one of 18.1143 - several ways.</para> 18.1144 - 18.1145 - <para id="x_157">It is possible that this other bug completely 18.1146 - <quote>masks</quote> yours, which is to say that it occurs 18.1147 - before your bug has a chance to manifest itself. If you can't 18.1148 - avoid that other bug (for example, it prevents your project 18.1149 - from building), and so can't tell whether your bug is present 18.1150 - in a particular changeset, the <command role="hg-cmd">hg 18.1151 - bisect</command> command cannot help you directly. Instead, 18.1152 - you can mark a changeset as untested by running <command 18.1153 - role="hg-cmd">hg bisect --skip</command>.</para> 18.1154 - 18.1155 - <para id="x_158">A different problem could arise if your test for a bug's 18.1156 - presence is not specific enough. If you check for <quote>my 18.1157 - program crashes</quote>, then both your crashing bug and an 18.1158 - unrelated crashing bug that masks it will look like the same 18.1159 - thing, and mislead <command role="hg-cmd">hg 18.1160 - bisect</command>.</para> 18.1161 - 18.1162 - <para id="x_159">Another useful situation in which to use <command 18.1163 - role="hg-cmd">hg bisect --skip</command> is if you can't 18.1164 - test a revision because your project was in a broken and hence 18.1165 - untestable state at that revision, perhaps because someone 18.1166 - checked in a change that prevented the project from 18.1167 - building.</para> 18.1168 - 18.1169 - </sect2> 18.1170 - <sect2> 18.1171 - <title>Bracket your search lazily</title> 18.1172 - 18.1173 - <para id="x_15a">Choosing the first <quote>good</quote> and 18.1174 - <quote>bad</quote> changesets that will mark the end points of 18.1175 - your search is often easy, but it bears a little discussion 18.1176 - nevertheless. From the perspective of <command 18.1177 - role="hg-cmd">hg bisect</command>, the <quote>newest</quote> 18.1178 - changeset is conventionally <quote>bad</quote>, and the older 18.1179 - changeset is <quote>good</quote>.</para> 18.1180 - 18.1181 - <para id="x_15b">If you're having trouble remembering when a suitable 18.1182 - <quote>good</quote> change was, so that you can tell <command 18.1183 - role="hg-cmd">hg bisect</command>, you could do worse than 18.1184 - testing changesets at random. Just remember to eliminate 18.1185 - contenders that can't possibly exhibit the bug (perhaps 18.1186 - because the feature with the bug isn't present yet) and those 18.1187 - where another problem masks the bug (as I discussed 18.1188 - above).</para> 18.1189 - 18.1190 - <para id="x_15c">Even if you end up <quote>early</quote> by thousands of 18.1191 - changesets or months of history, you will only add a handful 18.1192 - of tests to the total number that <command role="hg-cmd">hg 18.1193 - bisect</command> must perform, thanks to its logarithmic 18.1194 - behavior.</para> 18.1195 - 18.1196 - </sect2> 18.1197 - </sect1> 18.1198 -</chapter> 18.1199 - 18.1200 -<!-- 18.1201 -local variables: 18.1202 -sgml-parent-document: ("00book.xml" "book" "chapter") 18.1203 -end: 18.1204 --->
19.1 --- a/en/ch09-hook.xml Thu May 07 21:06:49 2009 -0700 19.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 19.3 @@ -1,1928 +0,0 @@ 19.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 19.5 - 19.6 -<chapter id="chap:hook"> 19.7 - <?dbhtml filename="handling-repository-events-with-hooks.html"?> 19.8 - <title>Handling repository events with hooks</title> 19.9 - 19.10 - <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform 19.11 - automated actions in response to events that occur in a 19.12 - repository. In some cases, you can even control Mercurial's 19.13 - response to those events.</para> 19.14 - 19.15 - <para id="x_1e7">The name Mercurial uses for one of these actions is a 19.16 - <emphasis>hook</emphasis>. Hooks are called 19.17 - <quote>triggers</quote> in some revision control systems, but the 19.18 - two names refer to the same idea.</para> 19.19 - 19.20 - <sect1> 19.21 - <title>An overview of hooks in Mercurial</title> 19.22 - 19.23 - <para id="x_1e8">Here is a brief list of the hooks that Mercurial 19.24 - supports. We will revisit each of these hooks in more detail 19.25 - later, in <xref linkend="sec:hook:ref"/>.</para> 19.26 - 19.27 - <para id="x_1f6">Each of the hooks whose description begins with the word 19.28 - <quote>Controlling</quote> has the ability to determine whether 19.29 - an activity can proceed. If the hook succeeds, the activity may 19.30 - proceed; if it fails, the activity is either not permitted or 19.31 - undone, depending on the hook.</para> 19.32 - 19.33 - <itemizedlist> 19.34 - <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This 19.35 - is run after a group of changesets has been brought into the 19.36 - repository from elsewhere.</para> 19.37 - </listitem> 19.38 - <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is 19.39 - run after a new changeset has been created in the local 19.40 - repository.</para> 19.41 - </listitem> 19.42 - <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is 19.43 - run once for each new changeset that is brought into the 19.44 - repository from elsewhere. Notice the difference from 19.45 - <literal role="hook">changegroup</literal>, which is run 19.46 - once per <emphasis>group</emphasis> of changesets brought 19.47 - in.</para> 19.48 - </listitem> 19.49 - <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is 19.50 - run after a group of changesets has been transmitted from 19.51 - this repository.</para> 19.52 - </listitem> 19.53 - <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>: 19.54 - This is run before starting to bring a group of changesets 19.55 - into the repository. 19.56 - </para> 19.57 - </listitem> 19.58 - <listitem><para id="x_1ee"><literal role="hook">precommit</literal>: 19.59 - Controlling. This is run before starting a commit. 19.60 - </para> 19.61 - </listitem> 19.62 - <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>: 19.63 - Controlling. This is run before starting to transmit a group 19.64 - of changesets from this repository. 19.65 - </para> 19.66 - </listitem> 19.67 - <listitem><para id="x_1f0"><literal role="hook">pretag</literal>: 19.68 - Controlling. This is run before creating a tag. 19.69 - </para> 19.70 - </listitem> 19.71 - <listitem><para id="x_1f1"><literal 19.72 - role="hook">pretxnchangegroup</literal>: Controlling. This 19.73 - is run after a group of changesets has been brought into the 19.74 - local repository from another, but before the transaction 19.75 - completes that will make the changes permanent in the 19.76 - repository. 19.77 - </para> 19.78 - </listitem> 19.79 - <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>: 19.80 - Controlling. This is run after a new changeset has been 19.81 - created in the local repository, but before the transaction 19.82 - completes that will make it permanent. 19.83 - </para> 19.84 - </listitem> 19.85 - <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>: 19.86 - Controlling. This is run before starting an update or merge 19.87 - of the working directory. 19.88 - </para> 19.89 - </listitem> 19.90 - <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run 19.91 - after a tag is created. 19.92 - </para> 19.93 - </listitem> 19.94 - <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is 19.95 - run after an update or merge of the working directory has 19.96 - finished. 19.97 - </para> 19.98 - </listitem></itemizedlist> 19.99 - 19.100 - </sect1> 19.101 - <sect1> 19.102 - <title>Hooks and security</title> 19.103 - 19.104 - <sect2> 19.105 - <title>Hooks are run with your privileges</title> 19.106 - 19.107 - <para id="x_1f7">When you run a Mercurial command in a repository, and the 19.108 - command causes a hook to run, that hook runs on 19.109 - <emphasis>your</emphasis> system, under 19.110 - <emphasis>your</emphasis> user account, with 19.111 - <emphasis>your</emphasis> privilege level. Since hooks are 19.112 - arbitrary pieces of executable code, you should treat them 19.113 - with an appropriate level of suspicion. Do not install a hook 19.114 - unless you are confident that you know who created it and what 19.115 - it does. 19.116 - </para> 19.117 - 19.118 - <para id="x_1f8">In some cases, you may be exposed to hooks that you did 19.119 - not install yourself. If you work with Mercurial on an 19.120 - unfamiliar system, Mercurial will run hooks defined in that 19.121 - system's global <filename role="special">~/.hgrc</filename> 19.122 - file. 19.123 - </para> 19.124 - 19.125 - <para id="x_1f9">If you are working with a repository owned by another 19.126 - user, Mercurial can run hooks defined in that user's 19.127 - repository, but it will still run them as <quote>you</quote>. 19.128 - For example, if you <command role="hg-cmd">hg pull</command> 19.129 - from that repository, and its <filename 19.130 - role="special">.hg/hgrc</filename> defines a local <literal 19.131 - role="hook">outgoing</literal> hook, that hook will run 19.132 - under your user account, even though you don't own that 19.133 - repository. 19.134 - </para> 19.135 - 19.136 - <note> 19.137 - <para id="x_1fa"> This only applies if you are pulling from a repository 19.138 - on a local or network filesystem. If you're pulling over 19.139 - http or ssh, any <literal role="hook">outgoing</literal> 19.140 - hook will run under whatever account is executing the server 19.141 - process, on the server. 19.142 - </para> 19.143 - </note> 19.144 - 19.145 - <para id="x_1fb">To see what hooks are defined in a repository, 19.146 - use the <command role="hg-cmd">hg showconfig hooks</command> 19.147 - command. If you are working in one repository, but talking to 19.148 - another that you do not own (e.g. using <command 19.149 - role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 19.150 - incoming</command>), remember that it is the other 19.151 - repository's hooks you should be checking, not your own. 19.152 - </para> 19.153 - </sect2> 19.154 - 19.155 - <sect2> 19.156 - <title>Hooks do not propagate</title> 19.157 - 19.158 - <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do 19.159 - not propagate when you clone, or pull from, a repository. The 19.160 - reason for this is simple: a hook is a completely arbitrary 19.161 - piece of executable code. It runs under your user identity, 19.162 - with your privilege level, on your machine. 19.163 - </para> 19.164 - 19.165 - <para id="x_1fd">It would be extremely reckless for any distributed 19.166 - revision control system to implement revision-controlled 19.167 - hooks, as this would offer an easily exploitable way to 19.168 - subvert the accounts of users of the revision control system. 19.169 - </para> 19.170 - 19.171 - <para id="x_1fe">Since Mercurial does not propagate hooks, if you are 19.172 - collaborating with other people on a common project, you 19.173 - should not assume that they are using the same Mercurial hooks 19.174 - as you are, or that theirs are correctly configured. You 19.175 - should document the hooks you expect people to use. 19.176 - </para> 19.177 - 19.178 - <para id="x_1ff">In a corporate intranet, this is somewhat easier to 19.179 - control, as you can for example provide a 19.180 - <quote>standard</quote> installation of Mercurial on an NFS 19.181 - filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will 19.182 - see. However, this too has its limits; see below. 19.183 - </para> 19.184 - </sect2> 19.185 - 19.186 - <sect2> 19.187 - <title>Hooks can be overridden</title> 19.188 - 19.189 - <para id="x_200">Mercurial allows you to override a hook definition by 19.190 - redefining the hook. You can disable it by setting its value 19.191 - to the empty string, or change its behavior as you wish. 19.192 - </para> 19.193 - 19.194 - <para id="x_201">If you deploy a system- or site-wide <filename 19.195 - role="special">~/.hgrc</filename> file that defines some 19.196 - hooks, you should thus understand that your users can disable 19.197 - or override those hooks. 19.198 - </para> 19.199 - </sect2> 19.200 - 19.201 - <sect2> 19.202 - <title>Ensuring that critical hooks are run</title> 19.203 - 19.204 - <para id="x_202">Sometimes you may want to enforce a policy that you do not 19.205 - want others to be able to work around. For example, you may 19.206 - have a requirement that every changeset must pass a rigorous 19.207 - set of tests. Defining this requirement via a hook in a 19.208 - site-wide <filename role="special">~/.hgrc</filename> won't 19.209 - work for remote users on laptops, and of course local users 19.210 - can subvert it at will by overriding the hook. 19.211 - </para> 19.212 - 19.213 - <para id="x_203">Instead, you can set up your policies for use of Mercurial 19.214 - so that people are expected to propagate changes through a 19.215 - well-known <quote>canonical</quote> server that you have 19.216 - locked down and configured appropriately. 19.217 - </para> 19.218 - 19.219 - <para id="x_204">One way to do this is via a combination of social 19.220 - engineering and technology. Set up a restricted-access 19.221 - account; users can push changes over the network to 19.222 - repositories managed by this account, but they cannot log into 19.223 - the account and run normal shell commands. In this scenario, 19.224 - a user can commit a changeset that contains any old garbage 19.225 - they want. 19.226 - </para> 19.227 - 19.228 - <para id="x_205">When someone pushes a changeset to the server that 19.229 - everyone pulls from, the server will test the changeset before 19.230 - it accepts it as permanent, and reject it if it fails to pass 19.231 - the test suite. If people only pull changes from this 19.232 - filtering server, it will serve to ensure that all changes 19.233 - that people pull have been automatically vetted. 19.234 - </para> 19.235 - 19.236 - </sect2> 19.237 - </sect1> 19.238 - 19.239 - <sect1 id="sec:hook:simple"> 19.240 - <title>A short tutorial on using hooks</title> 19.241 - 19.242 - <para id="x_212">It is easy to write a Mercurial hook. Let's start with a 19.243 - hook that runs when you finish a <command role="hg-cmd">hg 19.244 - commit</command>, and simply prints the hash of the changeset 19.245 - you just created. The hook is called <literal 19.246 - role="hook">commit</literal>. 19.247 - </para> 19.248 - 19.249 - <para id="x_213">All hooks follow the pattern in this example.</para> 19.250 - 19.251 -&interaction.hook.simple.init; 19.252 - 19.253 - <para id="x_214">You add an entry to the <literal 19.254 - role="rc-hooks">hooks</literal> section of your <filename 19.255 - role="special">~/.hgrc</filename>. On the left is the name of 19.256 - the event to trigger on; on the right is the action to take. As 19.257 - you can see, you can run an arbitrary shell command in a hook. 19.258 - Mercurial passes extra information to the hook using environment 19.259 - variables (look for <envar>HG_NODE</envar> in the example). 19.260 - </para> 19.261 - 19.262 - <sect2> 19.263 - <title>Performing multiple actions per event</title> 19.264 - 19.265 - <para id="x_215">Quite often, you will want to define more than one hook 19.266 - for a particular kind of event, as shown below.</para> 19.267 - 19.268 -&interaction.hook.simple.ext; 19.269 - 19.270 - <para id="x_216">Mercurial lets you do this by adding an 19.271 - <emphasis>extension</emphasis> to the end of a hook's name. 19.272 - You extend a hook's name by giving the name of the hook, 19.273 - followed by a full stop (the 19.274 - <quote><literal>.</literal></quote> character), followed by 19.275 - some more text of your choosing. For example, Mercurial will 19.276 - run both <literal>commit.foo</literal> and 19.277 - <literal>commit.bar</literal> when the 19.278 - <literal>commit</literal> event occurs. 19.279 - </para> 19.280 - 19.281 - <para id="x_217">To give a well-defined order of execution when there are 19.282 - multiple hooks defined for an event, Mercurial sorts hooks by 19.283 - extension, and executes the hook commands in this sorted 19.284 - order. In the above example, it will execute 19.285 - <literal>commit.bar</literal> before 19.286 - <literal>commit.foo</literal>, and <literal>commit</literal> 19.287 - before both. 19.288 - </para> 19.289 - 19.290 - <para id="x_218">It is a good idea to use a somewhat descriptive 19.291 - extension when you define a new hook. This will help you to 19.292 - remember what the hook was for. If the hook fails, you'll get 19.293 - an error message that contains the hook name and extension, so 19.294 - using a descriptive extension could give you an immediate hint 19.295 - as to why the hook failed (see <xref 19.296 - linkend="sec:hook:perm"/> for an example). 19.297 - </para> 19.298 - 19.299 - </sect2> 19.300 - <sect2 id="sec:hook:perm"> 19.301 - <title>Controlling whether an activity can proceed</title> 19.302 - 19.303 - <para id="x_219">In our earlier examples, we used the <literal 19.304 - role="hook">commit</literal> hook, which is run after a 19.305 - commit has completed. This is one of several Mercurial hooks 19.306 - that run after an activity finishes. Such hooks have no way 19.307 - of influencing the activity itself. 19.308 - </para> 19.309 - 19.310 - <para id="x_21a">Mercurial defines a number of events that occur before an 19.311 - activity starts; or after it starts, but before it finishes. 19.312 - Hooks that trigger on these events have the added ability to 19.313 - choose whether the activity can continue, or will abort. 19.314 - </para> 19.315 - 19.316 - <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs 19.317 - after a commit has all but completed. In other words, the 19.318 - metadata representing the changeset has been written out to 19.319 - disk, but the transaction has not yet been allowed to 19.320 - complete. The <literal role="hook">pretxncommit</literal> 19.321 - hook has the ability to decide whether the transaction can 19.322 - complete, or must be rolled back. 19.323 - </para> 19.324 - 19.325 - <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook 19.326 - exits with a status code of zero, the transaction is allowed 19.327 - to complete; the commit finishes; and the <literal 19.328 - role="hook">commit</literal> hook is run. If the <literal 19.329 - role="hook">pretxncommit</literal> hook exits with a 19.330 - non-zero status code, the transaction is rolled back; the 19.331 - metadata representing the changeset is erased; and the 19.332 - <literal role="hook">commit</literal> hook is not run. 19.333 - </para> 19.334 - 19.335 -&interaction.hook.simple.pretxncommit; 19.336 - 19.337 - <para id="x_21d">The hook in the example above checks that a commit comment 19.338 - contains a bug ID. If it does, the commit can complete. If 19.339 - not, the commit is rolled back. 19.340 - </para> 19.341 - 19.342 - </sect2> 19.343 - </sect1> 19.344 - <sect1> 19.345 - <title>Writing your own hooks</title> 19.346 - 19.347 - <para id="x_21e">When you are writing a hook, you might find it useful to run 19.348 - Mercurial either with the <option 19.349 - role="hg-opt-global">-v</option> option, or the <envar 19.350 - role="rc-item-ui">verbose</envar> config item set to 19.351 - <quote>true</quote>. When you do so, Mercurial will print a 19.352 - message before it calls each hook. 19.353 - </para> 19.354 - 19.355 - <sect2 id="sec:hook:lang"> 19.356 - <title>Choosing how your hook should run</title> 19.357 - 19.358 - <para id="x_21f">You can write a hook either as a normal 19.359 - program&emdash;typically a shell script&emdash;or as a Python 19.360 - function that is executed within the Mercurial process. 19.361 - </para> 19.362 - 19.363 - <para id="x_220">Writing a hook as an external program has the advantage 19.364 - that it requires no knowledge of Mercurial's internals. You 19.365 - can call normal Mercurial commands to get any added 19.366 - information you need. The trade-off is that external hooks 19.367 - are slower than in-process hooks. 19.368 - </para> 19.369 - 19.370 - <para id="x_221">An in-process Python hook has complete access to the 19.371 - Mercurial API, and does not <quote>shell out</quote> to 19.372 - another process, so it is inherently faster than an external 19.373 - hook. It is also easier to obtain much of the information 19.374 - that a hook requires by using the Mercurial API than by 19.375 - running Mercurial commands. 19.376 - </para> 19.377 - 19.378 - <para id="x_222">If you are comfortable with Python, or require high 19.379 - performance, writing your hooks in Python may be a good 19.380 - choice. However, when you have a straightforward hook to 19.381 - write and you don't need to care about performance (probably 19.382 - the majority of hooks), a shell script is perfectly fine. 19.383 - </para> 19.384 - 19.385 - </sect2> 19.386 - <sect2 id="sec:hook:param"> 19.387 - <title>Hook parameters</title> 19.388 - 19.389 - <para id="x_223">Mercurial calls each hook with a set of well-defined 19.390 - parameters. In Python, a parameter is passed as a keyword 19.391 - argument to your hook function. For an external program, a 19.392 - parameter is passed as an environment variable. 19.393 - </para> 19.394 - 19.395 - <para id="x_224">Whether your hook is written in Python or as a shell 19.396 - script, the hook-specific parameter names and values will be 19.397 - the same. A boolean parameter will be represented as a 19.398 - boolean value in Python, but as the number 1 (for 19.399 - <quote>true</quote>) or 0 (for <quote>false</quote>) as an 19.400 - environment variable for an external hook. If a hook 19.401 - parameter is named <literal>foo</literal>, the keyword 19.402 - argument for a Python hook will also be named 19.403 - <literal>foo</literal>, while the environment variable for an 19.404 - external hook will be named <literal>HG_FOO</literal>. 19.405 - </para> 19.406 - </sect2> 19.407 - 19.408 - <sect2> 19.409 - <title>Hook return values and activity control</title> 19.410 - 19.411 - <para id="x_225">A hook that executes successfully must exit with a status 19.412 - of zero if external, or return boolean <quote>false</quote> if 19.413 - in-process. Failure is indicated with a non-zero exit status 19.414 - from an external hook, or an in-process hook returning boolean 19.415 - <quote>true</quote>. If an in-process hook raises an 19.416 - exception, the hook is considered to have failed. 19.417 - </para> 19.418 - 19.419 - <para id="x_226">For a hook that controls whether an activity can proceed, 19.420 - zero/false means <quote>allow</quote>, while 19.421 - non-zero/true/exception means <quote>deny</quote>. 19.422 - </para> 19.423 - </sect2> 19.424 - 19.425 - <sect2> 19.426 - <title>Writing an external hook</title> 19.427 - 19.428 - <para id="x_227">When you define an external hook in your <filename 19.429 - role="special">~/.hgrc</filename> and the hook is run, its 19.430 - value is passed to your shell, which interprets it. This 19.431 - means that you can use normal shell constructs in the body of 19.432 - the hook. 19.433 - </para> 19.434 - 19.435 - <para id="x_228">An executable hook is always run with its current 19.436 - directory set to a repository's root directory. 19.437 - </para> 19.438 - 19.439 - <para id="x_229">Each hook parameter is passed in as an environment 19.440 - variable; the name is upper-cased, and prefixed with the 19.441 - string <quote><literal>HG_</literal></quote>. 19.442 - </para> 19.443 - 19.444 - <para id="x_22a">With the exception of hook parameters, Mercurial does not 19.445 - set or modify any environment variables when running a hook. 19.446 - This is useful to remember if you are writing a site-wide hook 19.447 - that may be run by a number of different users with differing 19.448 - environment variables set. In multi-user situations, you 19.449 - should not rely on environment variables being set to the 19.450 - values you have in your environment when testing the hook. 19.451 - </para> 19.452 - </sect2> 19.453 - 19.454 - <sect2> 19.455 - <title>Telling Mercurial to use an in-process hook</title> 19.456 - 19.457 - <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax 19.458 - for defining an in-process hook is slightly different than for 19.459 - an executable hook. The value of the hook must start with the 19.460 - text <quote><literal>python:</literal></quote>, and continue 19.461 - with the fully-qualified name of a callable object to use as 19.462 - the hook's value. 19.463 - </para> 19.464 - 19.465 - <para id="x_22c">The module in which a hook lives is automatically imported 19.466 - when a hook is run. So long as you have the module name and 19.467 - <envar>PYTHONPATH</envar> right, it should <quote>just 19.468 - work</quote>. 19.469 - </para> 19.470 - 19.471 - <para id="x_22d">The following <filename role="special">~/.hgrc</filename> 19.472 - example snippet illustrates the syntax and meaning of the 19.473 - notions we just described. 19.474 - </para> 19.475 - <programlisting>[hooks] 19.476 -commit.example = python:mymodule.submodule.myhook</programlisting> 19.477 - <para id="x_22e">When Mercurial runs the <literal>commit.example</literal> 19.478 - hook, it imports <literal>mymodule.submodule</literal>, looks 19.479 - for the callable object named <literal>myhook</literal>, and 19.480 - calls it. 19.481 - </para> 19.482 - </sect2> 19.483 - 19.484 - <sect2> 19.485 - <title>Writing an in-process hook</title> 19.486 - 19.487 - <para id="x_22f">The simplest in-process hook does nothing, but illustrates 19.488 - the basic shape of the hook API: 19.489 - </para> 19.490 - <programlisting>def myhook(ui, repo, **kwargs): 19.491 - pass</programlisting> 19.492 - <para id="x_230">The first argument to a Python hook is always a <literal 19.493 - role="py-mod-mercurial.ui">ui</literal> object. The second 19.494 - is a repository object; at the moment, it is always an 19.495 - instance of <literal 19.496 - role="py-mod-mercurial.localrepo">localrepository</literal>. 19.497 - Following these two arguments are other keyword arguments. 19.498 - Which ones are passed in depends on the hook being called, but 19.499 - a hook can ignore arguments it doesn't care about by dropping 19.500 - them into a keyword argument dict, as with 19.501 - <literal>**kwargs</literal> above. 19.502 - </para> 19.503 - 19.504 - </sect2> 19.505 - </sect1> 19.506 - <sect1> 19.507 - <title>Some hook examples</title> 19.508 - 19.509 - <sect2> 19.510 - <title>Writing meaningful commit messages</title> 19.511 - 19.512 - <para id="x_231">It's hard to imagine a useful commit message being very 19.513 - short. The simple <literal role="hook">pretxncommit</literal> 19.514 - hook of the example below will prevent you from committing a 19.515 - changeset with a message that is less than ten bytes long. 19.516 - </para> 19.517 - 19.518 -&interaction.hook.msglen.go; 19.519 - </sect2> 19.520 - 19.521 - <sect2> 19.522 - <title>Checking for trailing whitespace</title> 19.523 - 19.524 - <para id="x_232">An interesting use of a commit-related hook is to help you 19.525 - to write cleaner code. A simple example of <quote>cleaner 19.526 - code</quote> is the dictum that a change should not add any 19.527 - new lines of text that contain <quote>trailing 19.528 - whitespace</quote>. Trailing whitespace is a series of 19.529 - space and tab characters at the end of a line of text. In 19.530 - most cases, trailing whitespace is unnecessary, invisible 19.531 - noise, but it is occasionally problematic, and people often 19.532 - prefer to get rid of it. 19.533 - </para> 19.534 - 19.535 - <para id="x_233">You can use either the <literal 19.536 - role="hook">precommit</literal> or <literal 19.537 - role="hook">pretxncommit</literal> hook to tell whether you 19.538 - have a trailing whitespace problem. If you use the <literal 19.539 - role="hook">precommit</literal> hook, the hook will not know 19.540 - which files you are committing, so it will have to check every 19.541 - modified file in the repository for trailing white space. If 19.542 - you want to commit a change to just the file 19.543 - <filename>foo</filename>, but the file 19.544 - <filename>bar</filename> contains trailing whitespace, doing a 19.545 - check in the <literal role="hook">precommit</literal> hook 19.546 - will prevent you from committing <filename>foo</filename> due 19.547 - to the problem with <filename>bar</filename>. This doesn't 19.548 - seem right. 19.549 - </para> 19.550 - 19.551 - <para id="x_234">Should you choose the <literal 19.552 - role="hook">pretxncommit</literal> hook, the check won't 19.553 - occur until just before the transaction for the commit 19.554 - completes. This will allow you to check for problems only the 19.555 - exact files that are being committed. However, if you entered 19.556 - the commit message interactively and the hook fails, the 19.557 - transaction will roll back; you'll have to re-enter the commit 19.558 - message after you fix the trailing whitespace and run <command 19.559 - role="hg-cmd">hg commit</command> again. 19.560 - </para> 19.561 - 19.562 - &interaction.ch09-hook.ws.simple; 19.563 - 19.564 - <para id="x_235">In this example, we introduce a simple <literal 19.565 - role="hook">pretxncommit</literal> hook that checks for 19.566 - trailing whitespace. This hook is short, but not very 19.567 - helpful. It exits with an error status if a change adds a 19.568 - line with trailing whitespace to any file, but does not print 19.569 - any information that might help us to identify the offending 19.570 - file or line. It also has the nice property of not paying 19.571 - attention to unmodified lines; only lines that introduce new 19.572 - trailing whitespace cause problems. 19.573 - </para> 19.574 - 19.575 - &ch09-check_whitespace.py.lst; 19.576 - 19.577 - <para id="x_236">The above version is much more complex, but also more 19.578 - useful. It parses a unified diff to see if any lines add 19.579 - trailing whitespace, and prints the name of the file and the 19.580 - line number of each such occurrence. Even better, if the 19.581 - change adds trailing whitespace, this hook saves the commit 19.582 - comment and prints the name of the save file before exiting 19.583 - and telling Mercurial to roll the transaction back, so you can 19.584 - use the <option role="hg-opt-commit">-l filename</option> 19.585 - option to <command role="hg-cmd">hg commit</command> to reuse 19.586 - the saved commit message once you've corrected the problem. 19.587 - </para> 19.588 - 19.589 - &interaction.ch09-hook.ws.better; 19.590 - 19.591 - <para id="x_237">As a final aside, note in the example above the 19.592 - use of <command>sed</command>'s in-place editing feature to 19.593 - get rid of trailing whitespace from a file. This is concise 19.594 - and useful enough that I will reproduce it here (using 19.595 - <command>perl</command> for good measure).</para> 19.596 - <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting> 19.597 - 19.598 - </sect2> 19.599 - </sect1> 19.600 - <sect1> 19.601 - <title>Bundled hooks</title> 19.602 - 19.603 - <para id="x_238">Mercurial ships with several bundled hooks. You can find 19.604 - them in the <filename class="directory">hgext</filename> 19.605 - directory of a Mercurial source tree. If you are using a 19.606 - Mercurial binary package, the hooks will be located in the 19.607 - <filename class="directory">hgext</filename> directory of 19.608 - wherever your package installer put Mercurial. 19.609 - </para> 19.610 - 19.611 - <sect2> 19.612 - <title><literal role="hg-ext">acl</literal>&emdash;access 19.613 - control for parts of a repository</title> 19.614 - 19.615 - <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets 19.616 - you control which remote users are allowed to push changesets 19.617 - to a networked server. You can protect any portion of a 19.618 - repository (including the entire repo), so that a specific 19.619 - remote user can push changes that do not affect the protected 19.620 - portion. 19.621 - </para> 19.622 - 19.623 - <para id="x_23a">This extension implements access control based on the 19.624 - identity of the user performing a push, 19.625 - <emphasis>not</emphasis> on who committed the changesets 19.626 - they're pushing. It makes sense to use this hook only if you 19.627 - have a locked-down server environment that authenticates 19.628 - remote users, and you want to be sure that only specific users 19.629 - are allowed to push changes to that server. 19.630 - </para> 19.631 - 19.632 - <sect3> 19.633 - <title>Configuring the <literal role="hook">acl</literal> 19.634 - hook</title> 19.635 - 19.636 - <para id="x_23b">In order to manage incoming changesets, the <literal 19.637 - role="hg-ext">acl</literal> hook must be used as a 19.638 - <literal role="hook">pretxnchangegroup</literal> hook. This 19.639 - lets it see which files are modified by each incoming 19.640 - changeset, and roll back a group of changesets if they 19.641 - modify <quote>forbidden</quote> files. Example: 19.642 - </para> 19.643 - <programlisting>[hooks] 19.644 -pretxnchangegroup.acl = python:hgext.acl.hook</programlisting> 19.645 - 19.646 - <para id="x_23c">The <literal role="hg-ext">acl</literal> extension is 19.647 - configured using three sections. 19.648 - </para> 19.649 - 19.650 - <para id="x_23d">The <literal role="rc-acl">acl</literal> section has 19.651 - only one entry, <envar role="rc-item-acl">sources</envar>, 19.652 - which lists the sources of incoming changesets that the hook 19.653 - should pay attention to. You don't normally need to 19.654 - configure this section. 19.655 - </para> 19.656 - <itemizedlist> 19.657 - <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>: 19.658 - Control incoming changesets that are arriving from a 19.659 - remote repository over http or ssh. This is the default 19.660 - value of <envar role="rc-item-acl">sources</envar>, and 19.661 - usually the only setting you'll need for this 19.662 - configuration item. 19.663 - </para> 19.664 - </listitem> 19.665 - <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>: 19.666 - Control incoming changesets that are arriving via a pull 19.667 - from a local repository. 19.668 - </para> 19.669 - </listitem> 19.670 - <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>: 19.671 - Control incoming changesets that are arriving via a push 19.672 - from a local repository. 19.673 - </para> 19.674 - </listitem> 19.675 - <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>: 19.676 - Control incoming changesets that are arriving from 19.677 - another repository via a bundle. 19.678 - </para> 19.679 - </listitem></itemizedlist> 19.680 - 19.681 - <para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal> 19.682 - section controls the users that are allowed to add 19.683 - changesets to the repository. If this section is not 19.684 - present, all users that are not explicitly denied are 19.685 - allowed. If this section is present, all users that are not 19.686 - explicitly allowed are denied (so an empty section means 19.687 - that all users are denied). 19.688 - </para> 19.689 - 19.690 - <para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal> 19.691 - section determines which users are denied from adding 19.692 - changesets to the repository. If this section is not 19.693 - present or is empty, no users are denied. 19.694 - </para> 19.695 - 19.696 - <para id="x_244">The syntaxes for the <literal 19.697 - role="rc-acl.allow">acl.allow</literal> and <literal 19.698 - role="rc-acl.deny">acl.deny</literal> sections are 19.699 - identical. On the left of each entry is a glob pattern that 19.700 - matches files or directories, relative to the root of the 19.701 - repository; on the right, a user name. 19.702 - </para> 19.703 - 19.704 - <para id="x_245">In the following example, the user 19.705 - <literal>docwriter</literal> can only push changes to the 19.706 - <filename class="directory">docs</filename> subtree of the 19.707 - repository, while <literal>intern</literal> can push changes 19.708 - to any file or directory except <filename 19.709 - class="directory">source/sensitive</filename>. 19.710 - </para> 19.711 - <programlisting>[acl.allow] 19.712 -docs/** = docwriter 19.713 -[acl.deny] 19.714 -source/sensitive/** = intern</programlisting> 19.715 - 19.716 - </sect3> 19.717 - <sect3> 19.718 - <title>Testing and troubleshooting</title> 19.719 - 19.720 - <para id="x_246">If you want to test the <literal 19.721 - role="hg-ext">acl</literal> hook, run it with Mercurial's 19.722 - debugging output enabled. Since you'll probably be running 19.723 - it on a server where it's not convenient (or sometimes 19.724 - possible) to pass in the <option 19.725 - role="hg-opt-global">--debug</option> option, don't forget 19.726 - that you can enable debugging output in your <filename 19.727 - role="special">~/.hgrc</filename>: 19.728 - </para> 19.729 - <programlisting>[ui] 19.730 -debug = true</programlisting> 19.731 - <para id="x_247">With this enabled, the <literal 19.732 - role="hg-ext">acl</literal> hook will print enough 19.733 - information to let you figure out why it is allowing or 19.734 - forbidding pushes from specific users. 19.735 - </para> 19.736 - 19.737 - </sect3> </sect2> 19.738 - 19.739 - <sect2> 19.740 - <title><literal 19.741 - role="hg-ext">bugzilla</literal>&emdash;integration with 19.742 - Bugzilla</title> 19.743 - 19.744 - <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension 19.745 - adds a comment to a Bugzilla bug whenever it finds a reference 19.746 - to that bug ID in a commit comment. You can install this hook 19.747 - on a shared server, so that any time a remote user pushes 19.748 - changes to this server, the hook gets run. 19.749 - </para> 19.750 - 19.751 - <para id="x_249">It adds a comment to the bug that looks like this (you can 19.752 - configure the contents of the comment&emdash;see below): 19.753 - </para> 19.754 - <programlisting>Changeset aad8b264143a, made by Joe User 19.755 - <joe.user@domain.com> in the frobnitz repository, refers 19.756 - to this bug. For complete details, see 19.757 - http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 19.758 - Changeset description: Fix bug 10483 by guarding against some 19.759 - NULL pointers</programlisting> 19.760 - <para id="x_24a">The value of this hook is that it automates the process of 19.761 - updating a bug any time a changeset refers to it. If you 19.762 - configure the hook properly, it makes it easy for people to 19.763 - browse straight from a Bugzilla bug to a changeset that refers 19.764 - to that bug. 19.765 - </para> 19.766 - 19.767 - <para id="x_24b">You can use the code in this hook as a starting point for 19.768 - some more exotic Bugzilla integration recipes. Here are a few 19.769 - possibilities: 19.770 - </para> 19.771 - <itemizedlist> 19.772 - <listitem><para id="x_24c">Require that every changeset pushed to the 19.773 - server have a valid bug ID in its commit comment. In this 19.774 - case, you'd want to configure the hook as a <literal 19.775 - role="hook">pretxncommit</literal> hook. This would 19.776 - allow the hook to reject changes that didn't contain bug 19.777 - IDs. 19.778 - </para> 19.779 - </listitem> 19.780 - <listitem><para id="x_24d">Allow incoming changesets to automatically 19.781 - modify the <emphasis>state</emphasis> of a bug, as well as 19.782 - simply adding a comment. For example, the hook could 19.783 - recognise the string <quote>fixed bug 31337</quote> as 19.784 - indicating that it should update the state of bug 31337 to 19.785 - <quote>requires testing</quote>. 19.786 - </para> 19.787 - </listitem></itemizedlist> 19.788 - 19.789 - <sect3 id="sec:hook:bugzilla:config"> 19.790 - <title>Configuring the <literal role="hook">bugzilla</literal> 19.791 - hook</title> 19.792 - 19.793 - <para id="x_24e">You should configure this hook in your server's 19.794 - <filename role="special">~/.hgrc</filename> as an <literal 19.795 - role="hook">incoming</literal> hook, for example as 19.796 - follows: 19.797 - </para> 19.798 - <programlisting>[hooks] 19.799 -incoming.bugzilla = python:hgext.bugzilla.hook</programlisting> 19.800 - 19.801 - <para id="x_24f">Because of the specialised nature of this hook, and 19.802 - because Bugzilla was not written with this kind of 19.803 - integration in mind, configuring this hook is a somewhat 19.804 - involved process. 19.805 - </para> 19.806 - 19.807 - <para id="x_250">Before you begin, you must install the MySQL bindings 19.808 - for Python on the host(s) where you'll be running the hook. 19.809 - If this is not available as a binary package for your 19.810 - system, you can download it from 19.811 - <citation>web:mysql-python</citation>. 19.812 - </para> 19.813 - 19.814 - <para id="x_251">Configuration information for this hook lives in the 19.815 - <literal role="rc-bugzilla">bugzilla</literal> section of 19.816 - your <filename role="special">~/.hgrc</filename>. 19.817 - </para> 19.818 - <itemizedlist> 19.819 - <listitem><para id="x_252"><envar 19.820 - role="rc-item-bugzilla">version</envar>: The version 19.821 - of Bugzilla installed on the server. The database 19.822 - schema that Bugzilla uses changes occasionally, so this 19.823 - hook has to know exactly which schema to use.</para> 19.824 - </listitem> 19.825 - <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>: 19.826 - The hostname of the MySQL server that stores your 19.827 - Bugzilla data. The database must be configured to allow 19.828 - connections from whatever host you are running the 19.829 - <literal role="hook">bugzilla</literal> hook on. 19.830 - </para> 19.831 - </listitem> 19.832 - <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>: 19.833 - The username with which to connect to the MySQL server. 19.834 - The database must be configured to allow this user to 19.835 - connect from whatever host you are running the <literal 19.836 - role="hook">bugzilla</literal> hook on. This user 19.837 - must be able to access and modify Bugzilla tables. The 19.838 - default value of this item is <literal>bugs</literal>, 19.839 - which is the standard name of the Bugzilla user in a 19.840 - MySQL database. 19.841 - </para> 19.842 - </listitem> 19.843 - <listitem><para id="x_255"><envar 19.844 - role="rc-item-bugzilla">password</envar>: The MySQL 19.845 - password for the user you configured above. This is 19.846 - stored as plain text, so you should make sure that 19.847 - unauthorised users cannot read the <filename 19.848 - role="special">~/.hgrc</filename> file where you 19.849 - store this information. 19.850 - </para> 19.851 - </listitem> 19.852 - <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>: 19.853 - The name of the Bugzilla database on the MySQL server. 19.854 - The default value of this item is 19.855 - <literal>bugs</literal>, which is the standard name of 19.856 - the MySQL database where Bugzilla stores its data. 19.857 - </para> 19.858 - </listitem> 19.859 - <listitem><para id="x_257"><envar 19.860 - role="rc-item-bugzilla">notify</envar>: If you want 19.861 - Bugzilla to send out a notification email to subscribers 19.862 - after this hook has added a comment to a bug, you will 19.863 - need this hook to run a command whenever it updates the 19.864 - database. The command to run depends on where you have 19.865 - installed Bugzilla, but it will typically look something 19.866 - like this, if you have Bugzilla installed in <filename 19.867 - class="directory">/var/www/html/bugzilla</filename>: 19.868 - </para> 19.869 - <programlisting>cd /var/www/html/bugzilla && 19.870 - ./processmail %s nobody@nowhere.com</programlisting> 19.871 - </listitem> 19.872 - <listitem><para id="x_258"> The Bugzilla 19.873 - <literal>processmail</literal> program expects to be 19.874 - given a bug ID (the hook replaces 19.875 - <quote><literal>%s</literal></quote> with the bug ID) 19.876 - and an email address. It also expects to be able to 19.877 - write to some files in the directory that it runs in. 19.878 - If Bugzilla and this hook are not installed on the same 19.879 - machine, you will need to find a way to run 19.880 - <literal>processmail</literal> on the server where 19.881 - Bugzilla is installed. 19.882 - </para> 19.883 - </listitem></itemizedlist> 19.884 - 19.885 - </sect3> 19.886 - <sect3> 19.887 - <title>Mapping committer names to Bugzilla user names</title> 19.888 - 19.889 - <para id="x_259">By default, the <literal 19.890 - role="hg-ext">bugzilla</literal> hook tries to use the 19.891 - email address of a changeset's committer as the Bugzilla 19.892 - user name with which to update a bug. If this does not suit 19.893 - your needs, you can map committer email addresses to 19.894 - Bugzilla user names using a <literal 19.895 - role="rc-usermap">usermap</literal> section. 19.896 - </para> 19.897 - 19.898 - <para id="x_25a">Each item in the <literal 19.899 - role="rc-usermap">usermap</literal> section contains an 19.900 - email address on the left, and a Bugzilla user name on the 19.901 - right. 19.902 - </para> 19.903 - <programlisting>[usermap] 19.904 -jane.user@example.com = jane</programlisting> 19.905 - <para id="x_25b">You can either keep the <literal 19.906 - role="rc-usermap">usermap</literal> data in a normal 19.907 - <filename role="special">~/.hgrc</filename>, or tell the 19.908 - <literal role="hg-ext">bugzilla</literal> hook to read the 19.909 - information from an external <filename>usermap</filename> 19.910 - file. In the latter case, you can store 19.911 - <filename>usermap</filename> data by itself in (for example) 19.912 - a user-modifiable repository. This makes it possible to let 19.913 - your users maintain their own <envar 19.914 - role="rc-item-bugzilla">usermap</envar> entries. The main 19.915 - <filename role="special">~/.hgrc</filename> file might look 19.916 - like this: 19.917 - </para> 19.918 - <programlisting># regular hgrc file refers to external usermap file 19.919 -[bugzilla] 19.920 -usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> 19.921 - <para id="x_25c">While the <filename>usermap</filename> file that it 19.922 - refers to might look like this: 19.923 - </para> 19.924 - <programlisting># bugzilla-usermap.conf - inside a hg repository 19.925 -[usermap] stephanie@example.com = steph</programlisting> 19.926 - 19.927 - </sect3> 19.928 - <sect3> 19.929 - <title>Configuring the text that gets added to a bug</title> 19.930 - 19.931 - <para id="x_25d">You can configure the text that this hook adds as a 19.932 - comment; you specify it in the form of a Mercurial template. 19.933 - Several <filename role="special">~/.hgrc</filename> entries 19.934 - (still in the <literal role="rc-bugzilla">bugzilla</literal> 19.935 - section) control this behavior. 19.936 - </para> 19.937 - <itemizedlist> 19.938 - <listitem><para id="x_25e"><literal>strip</literal>: The number of 19.939 - leading path elements to strip from a repository's path 19.940 - name to construct a partial path for a URL. For example, 19.941 - if the repositories on your server live under <filename 19.942 - class="directory">/home/hg/repos</filename>, and you 19.943 - have a repository whose path is <filename 19.944 - class="directory">/home/hg/repos/app/tests</filename>, 19.945 - then setting <literal>strip</literal> to 19.946 - <literal>4</literal> will give a partial path of 19.947 - <filename class="directory">app/tests</filename>. The 19.948 - hook will make this partial path available when 19.949 - expanding a template, as <literal>webroot</literal>. 19.950 - </para> 19.951 - </listitem> 19.952 - <listitem><para id="x_25f"><literal>template</literal>: The text of the 19.953 - template to use. In addition to the usual 19.954 - changeset-related variables, this template can use 19.955 - <literal>hgweb</literal> (the value of the 19.956 - <literal>hgweb</literal> configuration item above) and 19.957 - <literal>webroot</literal> (the path constructed using 19.958 - <literal>strip</literal> above). 19.959 - </para> 19.960 - </listitem></itemizedlist> 19.961 - 19.962 - <para id="x_260">In addition, you can add a <envar 19.963 - role="rc-item-web">baseurl</envar> item to the <literal 19.964 - role="rc-web">web</literal> section of your <filename 19.965 - role="special">~/.hgrc</filename>. The <literal 19.966 - role="hg-ext">bugzilla</literal> hook will make this 19.967 - available when expanding a template, as the base string to 19.968 - use when constructing a URL that will let users browse from 19.969 - a Bugzilla comment to view a changeset. Example: 19.970 - </para> 19.971 - <programlisting>[web] 19.972 -baseurl = http://hg.domain.com/</programlisting> 19.973 - 19.974 - <para id="x_261">Here is an example set of <literal 19.975 - role="hg-ext">bugzilla</literal> hook config information. 19.976 - </para> 19.977 - 19.978 - &ch10-bugzilla-config.lst; 19.979 - 19.980 - </sect3> 19.981 - <sect3> 19.982 - <title>Testing and troubleshooting</title> 19.983 - 19.984 - <para id="x_262">The most common problems with configuring the <literal 19.985 - role="hg-ext">bugzilla</literal> hook relate to running 19.986 - Bugzilla's <filename>processmail</filename> script and 19.987 - mapping committer names to user names. 19.988 - </para> 19.989 - 19.990 - <para id="x_263">Recall from <xref 19.991 - linkend="sec:hook:bugzilla:config"/> above that the user 19.992 - that runs the Mercurial process on the server is also the 19.993 - one that will run the <filename>processmail</filename> 19.994 - script. The <filename>processmail</filename> script 19.995 - sometimes causes Bugzilla to write to files in its 19.996 - configuration directory, and Bugzilla's configuration files 19.997 - are usually owned by the user that your web server runs 19.998 - under. 19.999 - </para> 19.1000 - 19.1001 - <para id="x_264">You can cause <filename>processmail</filename> to be run 19.1002 - with the suitable user's identity using the 19.1003 - <command>sudo</command> command. Here is an example entry 19.1004 - for a <filename>sudoers</filename> file. 19.1005 - </para> 19.1006 - <programlisting>hg_user = (httpd_user) 19.1007 -NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting> 19.1008 - <para id="x_265">This allows the <literal>hg_user</literal> user to run a 19.1009 - <filename>processmail-wrapper</filename> program under the 19.1010 - identity of <literal>httpd_user</literal>. 19.1011 - </para> 19.1012 - 19.1013 - <para id="x_266">This indirection through a wrapper script is necessary, 19.1014 - because <filename>processmail</filename> expects to be run 19.1015 - with its current directory set to wherever you installed 19.1016 - Bugzilla; you can't specify that kind of constraint in a 19.1017 - <filename>sudoers</filename> file. The contents of the 19.1018 - wrapper script are simple: 19.1019 - </para> 19.1020 - <programlisting>#!/bin/sh 19.1021 -cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting> 19.1022 - <para id="x_267">It doesn't seem to matter what email address you pass to 19.1023 - <filename>processmail</filename>. 19.1024 - </para> 19.1025 - 19.1026 - <para id="x_268">If your <literal role="rc-usermap">usermap</literal> is 19.1027 - not set up correctly, users will see an error message from 19.1028 - the <literal role="hg-ext">bugzilla</literal> hook when they 19.1029 - push changes to the server. The error message will look 19.1030 - like this: 19.1031 - </para> 19.1032 - <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting> 19.1033 - <para id="x_269">What this means is that the committer's address, 19.1034 - <literal>john.q.public@example.com</literal>, is not a valid 19.1035 - Bugzilla user name, nor does it have an entry in your 19.1036 - <literal role="rc-usermap">usermap</literal> that maps it to 19.1037 - a valid Bugzilla user name. 19.1038 - </para> 19.1039 - 19.1040 - </sect3> </sect2> 19.1041 - 19.1042 - <sect2> 19.1043 - <title><literal role="hg-ext">notify</literal>&emdash;send email 19.1044 - notifications</title> 19.1045 - 19.1046 - <para id="x_26a">Although Mercurial's built-in web server provides RSS 19.1047 - feeds of changes in every repository, many people prefer to 19.1048 - receive change notifications via email. The <literal 19.1049 - role="hg-ext">notify</literal> hook lets you send out 19.1050 - notifications to a set of email addresses whenever changesets 19.1051 - arrive that those subscribers are interested in. 19.1052 - </para> 19.1053 - 19.1054 - <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal> 19.1055 - hook, the <literal role="hg-ext">notify</literal> hook is 19.1056 - template-driven, so you can customise the contents of the 19.1057 - notification messages that it sends. 19.1058 - </para> 19.1059 - 19.1060 - <para id="x_26c">By default, the <literal role="hg-ext">notify</literal> 19.1061 - hook includes a diff of every changeset that it sends out; you 19.1062 - can limit the size of the diff, or turn this feature off 19.1063 - entirely. It is useful for letting subscribers review changes 19.1064 - immediately, rather than clicking to follow a URL. 19.1065 - </para> 19.1066 - 19.1067 - <sect3> 19.1068 - <title>Configuring the <literal role="hg-ext">notify</literal> 19.1069 - hook</title> 19.1070 - 19.1071 - <para id="x_26d">You can set up the <literal 19.1072 - role="hg-ext">notify</literal> hook to send one email 19.1073 - message per incoming changeset, or one per incoming group of 19.1074 - changesets (all those that arrived in a single pull or 19.1075 - push). 19.1076 - </para> 19.1077 - <programlisting>[hooks] 19.1078 -# send one email per group of changes 19.1079 -changegroup.notify = python:hgext.notify.hook 19.1080 -# send one email per change 19.1081 -incoming.notify = python:hgext.notify.hook</programlisting> 19.1082 - 19.1083 - <para id="x_26e">Configuration information for this hook lives in the 19.1084 - <literal role="rc-notify">notify</literal> section of a 19.1085 - <filename role="special">~/.hgrc</filename> file. 19.1086 - </para> 19.1087 - <itemizedlist> 19.1088 - <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>: 19.1089 - By default, this hook does not send out email at all; 19.1090 - instead, it prints the message that it 19.1091 - <emphasis>would</emphasis> send. Set this item to 19.1092 - <literal>false</literal> to allow email to be sent. The 19.1093 - reason that sending of email is turned off by default is 19.1094 - that it takes several tries to configure this extension 19.1095 - exactly as you would like, and it would be bad form to 19.1096 - spam subscribers with a number of <quote>broken</quote> 19.1097 - notifications while you debug your configuration. 19.1098 - </para> 19.1099 - </listitem> 19.1100 - <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>: 19.1101 - The path to a configuration file that contains 19.1102 - subscription information. This is kept separate from 19.1103 - the main <filename role="special">~/.hgrc</filename> so 19.1104 - that you can maintain it in a repository of its own. 19.1105 - People can then clone that repository, update their 19.1106 - subscriptions, and push the changes back to your server. 19.1107 - </para> 19.1108 - </listitem> 19.1109 - <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>: 19.1110 - The number of leading path separator characters to strip 19.1111 - from a repository's path, when deciding whether a 19.1112 - repository has subscribers. For example, if the 19.1113 - repositories on your server live in <filename 19.1114 - class="directory">/home/hg/repos</filename>, and 19.1115 - <literal role="hg-ext">notify</literal> is considering a 19.1116 - repository named <filename 19.1117 - class="directory">/home/hg/repos/shared/test</filename>, 19.1118 - setting <envar role="rc-item-notify">strip</envar> to 19.1119 - <literal>4</literal> will cause <literal 19.1120 - role="hg-ext">notify</literal> to trim the path it 19.1121 - considers down to <filename 19.1122 - class="directory">shared/test</filename>, and it will 19.1123 - match subscribers against that. 19.1124 - </para> 19.1125 - </listitem> 19.1126 - <listitem><para id="x_272"><envar 19.1127 - role="rc-item-notify">template</envar>: The template 19.1128 - text to use when sending messages. This specifies both 19.1129 - the contents of the message header and its body. 19.1130 - </para> 19.1131 - </listitem> 19.1132 - <listitem><para id="x_273"><envar 19.1133 - role="rc-item-notify">maxdiff</envar>: The maximum 19.1134 - number of lines of diff data to append to the end of a 19.1135 - message. If a diff is longer than this, it is 19.1136 - truncated. By default, this is set to 300. Set this to 19.1137 - <literal>0</literal> to omit diffs from notification 19.1138 - emails. 19.1139 - </para> 19.1140 - </listitem> 19.1141 - <listitem><para id="x_274"><envar 19.1142 - role="rc-item-notify">sources</envar>: A list of 19.1143 - sources of changesets to consider. This lets you limit 19.1144 - <literal role="hg-ext">notify</literal> to only sending 19.1145 - out email about changes that remote users pushed into 19.1146 - this repository via a server, for example. See 19.1147 - <xref linkend="sec:hook:sources"/> for the sources you 19.1148 - can specify here. 19.1149 - </para> 19.1150 - </listitem></itemizedlist> 19.1151 - 19.1152 - <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar> 19.1153 - item in the <literal role="rc-web">web</literal> section, 19.1154 - you can use it in a template; it will be available as 19.1155 - <literal>webroot</literal>. 19.1156 - </para> 19.1157 - 19.1158 - <para id="x_276">Here is an example set of <literal 19.1159 - role="hg-ext">notify</literal> configuration information. 19.1160 - </para> 19.1161 - 19.1162 - &ch10-notify-config.lst; 19.1163 - 19.1164 - <para id="x_277">This will produce a message that looks like the 19.1165 - following: 19.1166 - </para> 19.1167 - 19.1168 - &ch10-notify-config-mail.lst; 19.1169 - 19.1170 - </sect3> 19.1171 - <sect3> 19.1172 - <title>Testing and troubleshooting</title> 19.1173 - 19.1174 - <para id="x_278">Do not forget that by default, the <literal 19.1175 - role="hg-ext">notify</literal> extension <emphasis>will not 19.1176 - send any mail</emphasis> until you explicitly configure it to do so, 19.1177 - by setting <envar role="rc-item-notify">test</envar> to 19.1178 - <literal>false</literal>. Until you do that, it simply 19.1179 - prints the message it <emphasis>would</emphasis> send. 19.1180 - </para> 19.1181 - 19.1182 - </sect3> 19.1183 - </sect2> 19.1184 - </sect1> 19.1185 - <sect1 id="sec:hook:ref"> 19.1186 - <title>Information for writers of hooks</title> 19.1187 - 19.1188 - <sect2> 19.1189 - <title>In-process hook execution</title> 19.1190 - 19.1191 - <para id="x_279">An in-process hook is called with arguments of the 19.1192 - following form: 19.1193 - </para> 19.1194 - <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting> 19.1195 - <para id="x_27a">The <literal>ui</literal> parameter is a <literal 19.1196 - role="py-mod-mercurial.ui">ui</literal> object. The 19.1197 - <literal>repo</literal> parameter is a <literal 19.1198 - role="py-mod-mercurial.localrepo">localrepository</literal> 19.1199 - object. The names and values of the 19.1200 - <literal>**kwargs</literal> parameters depend on the hook 19.1201 - being invoked, with the following common features: 19.1202 - </para> 19.1203 - <itemizedlist> 19.1204 - <listitem><para id="x_27b">If a parameter is named 19.1205 - <literal>node</literal> or <literal>parentN</literal>, it 19.1206 - will contain a hexadecimal changeset ID. The empty string 19.1207 - is used to represent <quote>null changeset ID</quote> 19.1208 - instead of a string of zeroes. 19.1209 - </para> 19.1210 - </listitem> 19.1211 - <listitem><para id="x_27c">If a parameter is named 19.1212 - <literal>url</literal>, it will contain the URL of a 19.1213 - remote repository, if that can be determined. 19.1214 - </para> 19.1215 - </listitem> 19.1216 - <listitem><para id="x_27d">Boolean-valued parameters are represented as 19.1217 - Python <literal>bool</literal> objects. 19.1218 - </para> 19.1219 - </listitem></itemizedlist> 19.1220 - 19.1221 - <para id="x_27e">An in-process hook is called without a change to the 19.1222 - process's working directory (unlike external hooks, which are 19.1223 - run in the root of the repository). It must not change the 19.1224 - process's working directory, or it will cause any calls it 19.1225 - makes into the Mercurial API to fail. 19.1226 - </para> 19.1227 - 19.1228 - <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it 19.1229 - is considered to have succeeded. If it returns a boolean 19.1230 - <quote>true</quote> value or raises an exception, it is 19.1231 - considered to have failed. A useful way to think of the 19.1232 - calling convention is <quote>tell me if you fail</quote>. 19.1233 - </para> 19.1234 - 19.1235 - <para id="x_280">Note that changeset IDs are passed into Python hooks as 19.1236 - hexadecimal strings, not the binary hashes that Mercurial's 19.1237 - APIs normally use. To convert a hash from hex to binary, use 19.1238 - the <literal>bin</literal> function. 19.1239 - </para> 19.1240 - </sect2> 19.1241 - 19.1242 - <sect2> 19.1243 - <title>External hook execution</title> 19.1244 - 19.1245 - <para id="x_281">An external hook is passed to the shell of the user 19.1246 - running Mercurial. Features of that shell, such as variable 19.1247 - substitution and command redirection, are available. The hook 19.1248 - is run in the root directory of the repository (unlike 19.1249 - in-process hooks, which are run in the same directory that 19.1250 - Mercurial was run in). 19.1251 - </para> 19.1252 - 19.1253 - <para id="x_282">Hook parameters are passed to the hook as environment 19.1254 - variables. Each environment variable's name is converted in 19.1255 - upper case and prefixed with the string 19.1256 - <quote><literal>HG_</literal></quote>. For example, if the 19.1257 - name of a parameter is <quote><literal>node</literal></quote>, 19.1258 - the name of the environment variable representing that 19.1259 - parameter will be <quote><literal>HG_NODE</literal></quote>. 19.1260 - </para> 19.1261 - 19.1262 - <para id="x_283">A boolean parameter is represented as the string 19.1263 - <quote><literal>1</literal></quote> for <quote>true</quote>, 19.1264 - <quote><literal>0</literal></quote> for <quote>false</quote>. 19.1265 - If an environment variable is named <envar>HG_NODE</envar>, 19.1266 - <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it 19.1267 - contains a changeset ID represented as a hexadecimal string. 19.1268 - The empty string is used to represent <quote>null changeset 19.1269 - ID</quote> instead of a string of zeroes. If an environment 19.1270 - variable is named <envar>HG_URL</envar>, it will contain the 19.1271 - URL of a remote repository, if that can be determined. 19.1272 - </para> 19.1273 - 19.1274 - <para id="x_284">If a hook exits with a status of zero, it is considered to 19.1275 - have succeeded. If it exits with a non-zero status, it is 19.1276 - considered to have failed. 19.1277 - </para> 19.1278 - </sect2> 19.1279 - 19.1280 - <sect2> 19.1281 - <title>Finding out where changesets come from</title> 19.1282 - 19.1283 - <para id="x_285">A hook that involves the transfer of changesets between a 19.1284 - local repository and another may be able to find out 19.1285 - information about the <quote>far side</quote>. Mercurial 19.1286 - knows <emphasis>how</emphasis> changes are being transferred, 19.1287 - and in many cases <emphasis>where</emphasis> they are being 19.1288 - transferred to or from. 19.1289 - </para> 19.1290 - 19.1291 - <sect3 id="sec:hook:sources"> 19.1292 - <title>Sources of changesets</title> 19.1293 - 19.1294 - <para id="x_286">Mercurial will tell a hook what means are, or were, used 19.1295 - to transfer changesets between repositories. This is 19.1296 - provided by Mercurial in a Python parameter named 19.1297 - <literal>source</literal>, or an environment variable named 19.1298 - <envar>HG_SOURCE</envar>. 19.1299 - </para> 19.1300 - 19.1301 - <itemizedlist> 19.1302 - <listitem><para id="x_287"><literal>serve</literal>: Changesets are 19.1303 - transferred to or from a remote repository over http or 19.1304 - ssh. 19.1305 - </para> 19.1306 - </listitem> 19.1307 - <listitem><para id="x_288"><literal>pull</literal>: Changesets are 19.1308 - being transferred via a pull from one repository into 19.1309 - another. 19.1310 - </para> 19.1311 - </listitem> 19.1312 - <listitem><para id="x_289"><literal>push</literal>: Changesets are 19.1313 - being transferred via a push from one repository into 19.1314 - another. 19.1315 - </para> 19.1316 - </listitem> 19.1317 - <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are 19.1318 - being transferred to or from a bundle. 19.1319 - </para> 19.1320 - </listitem></itemizedlist> 19.1321 - </sect3> 19.1322 - 19.1323 - <sect3 id="sec:hook:url"> 19.1324 - <title>Where changes are going&emdash;remote repository 19.1325 - URLs</title> 19.1326 - 19.1327 - <para id="x_28b">When possible, Mercurial will tell a hook the location 19.1328 - of the <quote>far side</quote> of an activity that transfers 19.1329 - changeset data between repositories. This is provided by 19.1330 - Mercurial in a Python parameter named 19.1331 - <literal>url</literal>, or an environment variable named 19.1332 - <envar>HG_URL</envar>. 19.1333 - </para> 19.1334 - 19.1335 - <para id="x_28c">This information is not always known. If a hook is 19.1336 - invoked in a repository that is being served via http or 19.1337 - ssh, Mercurial cannot tell where the remote repository is, 19.1338 - but it may know where the client is connecting from. In 19.1339 - such cases, the URL will take one of the following forms: 19.1340 - </para> 19.1341 - <itemizedlist> 19.1342 - <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 19.1343 - ssh client, at the IP address 19.1344 - <literal>1.2.3.4</literal>. 19.1345 - </para> 19.1346 - </listitem> 19.1347 - <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 19.1348 - http client, at the IP address 19.1349 - <literal>1.2.3.4</literal>. If the client is using SSL, 19.1350 - this will be of the form 19.1351 - <literal>remote:https:1.2.3.4</literal>. 19.1352 - </para> 19.1353 - </listitem> 19.1354 - <listitem><para id="x_28f">Empty&emdash;no information could be 19.1355 - discovered about the remote client. 19.1356 - </para> 19.1357 - </listitem></itemizedlist> 19.1358 - </sect3> 19.1359 - </sect2> 19.1360 - </sect1> 19.1361 - <sect1> 19.1362 - <title>Hook reference</title> 19.1363 - 19.1364 - <sect2 id="sec:hook:changegroup"> 19.1365 - <title><literal role="hook">changegroup</literal>&emdash;after 19.1366 - remote changesets added</title> 19.1367 - 19.1368 - <para id="x_290">This hook is run after a group of pre-existing changesets 19.1369 - has been added to the repository, for example via a <command 19.1370 - role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 19.1371 - unbundle</command>. This hook is run once per operation 19.1372 - that added one or more changesets. This is in contrast to the 19.1373 - <literal role="hook">incoming</literal> hook, which is run 19.1374 - once per changeset, regardless of whether the changesets 19.1375 - arrive in a group. 19.1376 - </para> 19.1377 - 19.1378 - <para id="x_291">Some possible uses for this hook include kicking off an 19.1379 - automated build or test of the added changesets, updating a 19.1380 - bug database, or notifying subscribers that a repository 19.1381 - contains new changes. 19.1382 - </para> 19.1383 - 19.1384 - <para id="x_292">Parameters to this hook: 19.1385 - </para> 19.1386 - <itemizedlist> 19.1387 - <listitem><para id="x_293"><literal>node</literal>: A changeset ID. The 19.1388 - changeset ID of the first changeset in the group that was 19.1389 - added. All changesets between this and 19.1390 - <literal role="tag">tip</literal>, inclusive, were added by a single 19.1391 - <command role="hg-cmd">hg pull</command>, <command 19.1392 - role="hg-cmd">hg push</command> or <command 19.1393 - role="hg-cmd">hg unbundle</command>. 19.1394 - </para> 19.1395 - </listitem> 19.1396 - <listitem><para id="x_294"><literal>source</literal>: A 19.1397 - string. The source of these changes. See <xref 19.1398 - linkend="sec:hook:sources"/> for details. 19.1399 - </para> 19.1400 - </listitem> 19.1401 - <listitem><para id="x_295"><literal>url</literal>: A URL. The 19.1402 - location of the remote repository, if known. See <xref 19.1403 - linkend="sec:hook:url"/> for more information. 19.1404 - </para> 19.1405 - </listitem></itemizedlist> 19.1406 - 19.1407 - <para id="x_296">See also: <literal 19.1408 - role="hook">incoming</literal> (<xref 19.1409 - linkend="sec:hook:incoming"/>), <literal 19.1410 - role="hook">prechangegroup</literal> (<xref 19.1411 - linkend="sec:hook:prechangegroup"/>), <literal 19.1412 - role="hook">pretxnchangegroup</literal> (<xref 19.1413 - linkend="sec:hook:pretxnchangegroup"/>) 19.1414 - </para> 19.1415 - </sect2> 19.1416 - 19.1417 - <sect2 id="sec:hook:commit"> 19.1418 - <title><literal role="hook">commit</literal>&emdash;after a new 19.1419 - changeset is created</title> 19.1420 - 19.1421 - <para id="x_297">This hook is run after a new changeset has been created. 19.1422 - </para> 19.1423 - 19.1424 - <para id="x_298">Parameters to this hook: 19.1425 - </para> 19.1426 - <itemizedlist> 19.1427 - <listitem><para id="x_299"><literal>node</literal>: A changeset ID. The 19.1428 - changeset ID of the newly committed changeset. 19.1429 - </para> 19.1430 - </listitem> 19.1431 - <listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID. 19.1432 - The changeset ID of the first parent of the newly 19.1433 - committed changeset. 19.1434 - </para> 19.1435 - </listitem> 19.1436 - <listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID. 19.1437 - The changeset ID of the second parent of the newly 19.1438 - committed changeset. 19.1439 - </para> 19.1440 - </listitem></itemizedlist> 19.1441 - 19.1442 - <para id="x_29c">See also: <literal 19.1443 - role="hook">precommit</literal> (<xref 19.1444 - linkend="sec:hook:precommit"/>), <literal 19.1445 - role="hook">pretxncommit</literal> (<xref 19.1446 - linkend="sec:hook:pretxncommit"/>) 19.1447 - </para> 19.1448 - </sect2> 19.1449 - 19.1450 - <sect2 id="sec:hook:incoming"> 19.1451 - <title><literal role="hook">incoming</literal>&emdash;after one 19.1452 - remote changeset is added</title> 19.1453 - 19.1454 - <para id="x_29d">This hook is run after a pre-existing changeset has been 19.1455 - added to the repository, for example via a <command 19.1456 - role="hg-cmd">hg push</command>. If a group of changesets 19.1457 - was added in a single operation, this hook is called once for 19.1458 - each added changeset. 19.1459 - </para> 19.1460 - 19.1461 - <para id="x_29e">You can use this hook for the same purposes as 19.1462 - the <literal role="hook">changegroup</literal> hook (<xref 19.1463 - linkend="sec:hook:changegroup"/>); it's simply more 19.1464 - convenient sometimes to run a hook once per group of 19.1465 - changesets, while other times it's handier once per changeset. 19.1466 - </para> 19.1467 - 19.1468 - <para id="x_29f">Parameters to this hook: 19.1469 - </para> 19.1470 - <itemizedlist> 19.1471 - <listitem><para id="x_2a0"><literal>node</literal>: A changeset ID. The 19.1472 - ID of the newly added changeset. 19.1473 - </para> 19.1474 - </listitem> 19.1475 - <listitem><para id="x_2a1"><literal>source</literal>: A 19.1476 - string. The source of these changes. See <xref 19.1477 - linkend="sec:hook:sources"/> for details. 19.1478 - </para> 19.1479 - </listitem> 19.1480 - <listitem><para id="x_2a2"><literal>url</literal>: A URL. The 19.1481 - location of the remote repository, if known. See <xref 19.1482 - linkend="sec:hook:url"/> for more information. 19.1483 - </para> 19.1484 - </listitem></itemizedlist> 19.1485 - 19.1486 - <para id="x_2a3">See also: <literal 19.1487 - role="hook">changegroup</literal> (<xref 19.1488 - linkend="sec:hook:changegroup"/>) <literal 19.1489 - role="hook">prechangegroup</literal> (<xref 19.1490 - linkend="sec:hook:prechangegroup"/>), <literal 19.1491 - role="hook">pretxnchangegroup</literal> (<xref 19.1492 - linkend="sec:hook:pretxnchangegroup"/>) 19.1493 - </para> 19.1494 - </sect2> 19.1495 - 19.1496 - <sect2 id="sec:hook:outgoing"> 19.1497 - <title><literal role="hook">outgoing</literal>&emdash;after 19.1498 - changesets are propagated</title> 19.1499 - 19.1500 - <para id="x_2a4">This hook is run after a group of changesets has been 19.1501 - propagated out of this repository, for example by a <command 19.1502 - role="hg-cmd">hg push</command> or <command role="hg-cmd">hg 19.1503 - bundle</command> command. 19.1504 - </para> 19.1505 - 19.1506 - <para id="x_2a5">One possible use for this hook is to notify administrators 19.1507 - that changes have been pulled. 19.1508 - </para> 19.1509 - 19.1510 - <para id="x_2a6">Parameters to this hook: 19.1511 - </para> 19.1512 - <itemizedlist> 19.1513 - <listitem><para id="x_2a7"><literal>node</literal>: A changeset ID. The 19.1514 - changeset ID of the first changeset of the group that was 19.1515 - sent. 19.1516 - </para> 19.1517 - </listitem> 19.1518 - <listitem><para id="x_2a8"><literal>source</literal>: A string. The 19.1519 - source of the of the operation (see <xref 19.1520 - linkend="sec:hook:sources"/>). If a remote 19.1521 - client pulled changes from this repository, 19.1522 - <literal>source</literal> will be 19.1523 - <literal>serve</literal>. If the client that obtained 19.1524 - changes from this repository was local, 19.1525 - <literal>source</literal> will be 19.1526 - <literal>bundle</literal>, <literal>pull</literal>, or 19.1527 - <literal>push</literal>, depending on the operation the 19.1528 - client performed. 19.1529 - </para> 19.1530 - </listitem> 19.1531 - <listitem><para id="x_2a9"><literal>url</literal>: A URL. The 19.1532 - location of the remote repository, if known. See <xref 19.1533 - linkend="sec:hook:url"/> for more information. 19.1534 - </para> 19.1535 - </listitem></itemizedlist> 19.1536 - 19.1537 - <para id="x_2aa">See also: <literal 19.1538 - role="hook">preoutgoing</literal> (<xref 19.1539 - linkend="sec:hook:preoutgoing"/>) 19.1540 - </para> 19.1541 - </sect2> 19.1542 - 19.1543 - <sect2 id="sec:hook:prechangegroup"> 19.1544 - <title><literal 19.1545 - role="hook">prechangegroup</literal>&emdash;before starting 19.1546 - to add remote changesets</title> 19.1547 - 19.1548 - <para id="x_2ab">This controlling hook is run before Mercurial begins to 19.1549 - add a group of changesets from another repository. 19.1550 - </para> 19.1551 - 19.1552 - <para id="x_2ac">This hook does not have any information about the 19.1553 - changesets to be added, because it is run before transmission 19.1554 - of those changesets is allowed to begin. If this hook fails, 19.1555 - the changesets will not be transmitted. 19.1556 - </para> 19.1557 - 19.1558 - <para id="x_2ad">One use for this hook is to prevent external changes from 19.1559 - being added to a repository. For example, you could use this 19.1560 - to <quote>freeze</quote> a server-hosted branch temporarily or 19.1561 - permanently so that users cannot push to it, while still 19.1562 - allowing a local administrator to modify the repository. 19.1563 - </para> 19.1564 - 19.1565 - <para id="x_2ae">Parameters to this hook: 19.1566 - </para> 19.1567 - <itemizedlist> 19.1568 - <listitem><para id="x_2af"><literal>source</literal>: A string. The 19.1569 - source of these changes. See <xref 19.1570 - linkend="sec:hook:sources"/> for details. 19.1571 - </para> 19.1572 - </listitem> 19.1573 - <listitem><para id="x_2b0"><literal>url</literal>: A URL. The 19.1574 - location of the remote repository, if known. See <xref 19.1575 - linkend="sec:hook:url"/> for more information. 19.1576 - </para> 19.1577 - </listitem></itemizedlist> 19.1578 - 19.1579 - <para id="x_2b1">See also: <literal 19.1580 - role="hook">changegroup</literal> (<xref 19.1581 - linkend="sec:hook:changegroup"/>), <literal 19.1582 - role="hook">incoming</literal> (<xref 19.1583 - linkend="sec:hook:incoming"/>), <literal 19.1584 - role="hook">pretxnchangegroup</literal> (<xref 19.1585 - linkend="sec:hook:pretxnchangegroup"/>) 19.1586 - </para> 19.1587 - </sect2> 19.1588 - 19.1589 - <sect2 id="sec:hook:precommit"> 19.1590 - <title><literal role="hook">precommit</literal>&emdash;before 19.1591 - starting to commit a changeset</title> 19.1592 - 19.1593 - <para id="x_2b2">This hook is run before Mercurial begins to commit a new 19.1594 - changeset. It is run before Mercurial has any of the metadata 19.1595 - for the commit, such as the files to be committed, the commit 19.1596 - message, or the commit date. 19.1597 - </para> 19.1598 - 19.1599 - <para id="x_2b3">One use for this hook is to disable the ability to commit 19.1600 - new changesets, while still allowing incoming changesets. 19.1601 - Another is to run a build or test, and only allow the commit 19.1602 - to begin if the build or test succeeds. 19.1603 - </para> 19.1604 - 19.1605 - <para id="x_2b4">Parameters to this hook: 19.1606 - </para> 19.1607 - <itemizedlist> 19.1608 - <listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID. 19.1609 - The changeset ID of the first parent of the working 19.1610 - directory. 19.1611 - </para> 19.1612 - </listitem> 19.1613 - <listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID. 19.1614 - The changeset ID of the second parent of the working 19.1615 - directory. 19.1616 - </para> 19.1617 - </listitem></itemizedlist> 19.1618 - <para id="x_2b7">If the commit proceeds, the parents of the working 19.1619 - directory will become the parents of the new changeset. 19.1620 - </para> 19.1621 - 19.1622 - <para id="x_2b8">See also: <literal role="hook">commit</literal> 19.1623 - (<xref linkend="sec:hook:commit"/>), <literal 19.1624 - role="hook">pretxncommit</literal> (<xref 19.1625 - linkend="sec:hook:pretxncommit"/>) 19.1626 - </para> 19.1627 - </sect2> 19.1628 - 19.1629 - <sect2 id="sec:hook:preoutgoing"> 19.1630 - <title><literal role="hook">preoutgoing</literal>&emdash;before 19.1631 - starting to propagate changesets</title> 19.1632 - 19.1633 - <para id="x_2b9">This hook is invoked before Mercurial knows the identities 19.1634 - of the changesets to be transmitted. 19.1635 - </para> 19.1636 - 19.1637 - <para id="x_2ba">One use for this hook is to prevent changes from being 19.1638 - transmitted to another repository. 19.1639 - </para> 19.1640 - 19.1641 - <para id="x_2bb">Parameters to this hook: 19.1642 - </para> 19.1643 - <itemizedlist> 19.1644 - <listitem><para id="x_2bc"><literal>source</literal>: A 19.1645 - string. The source of the operation that is attempting to 19.1646 - obtain changes from this repository (see <xref 19.1647 - linkend="sec:hook:sources"/>). See the documentation 19.1648 - for the <literal>source</literal> parameter to the 19.1649 - <literal role="hook">outgoing</literal> hook, in 19.1650 - <xref linkend="sec:hook:outgoing"/>, for possible values 19.1651 - of this parameter. 19.1652 - </para> 19.1653 - </listitem> 19.1654 - <listitem><para id="x_2bd"><literal>url</literal>: A URL. The 19.1655 - location of the remote repository, if known. See <xref 19.1656 - linkend="sec:hook:url"/> for more information. 19.1657 - </para> 19.1658 - </listitem></itemizedlist> 19.1659 - 19.1660 - <para id="x_2be">See also: <literal 19.1661 - role="hook">outgoing</literal> (<xref 19.1662 - linkend="sec:hook:outgoing"/>) 19.1663 - </para> 19.1664 - </sect2> 19.1665 - 19.1666 - <sect2 id="sec:hook:pretag"> 19.1667 - <title><literal role="hook">pretag</literal>&emdash;before 19.1668 - tagging a changeset</title> 19.1669 - 19.1670 - <para id="x_2bf">This controlling hook is run before a tag is created. If 19.1671 - the hook succeeds, creation of the tag proceeds. If the hook 19.1672 - fails, the tag is not created. 19.1673 - </para> 19.1674 - 19.1675 - <para id="x_2c0">Parameters to this hook: 19.1676 - </para> 19.1677 - <itemizedlist> 19.1678 - <listitem><para id="x_2c1"><literal>local</literal>: A boolean. Whether 19.1679 - the tag is local to this repository instance (i.e. stored 19.1680 - in <filename role="special">.hg/localtags</filename>) or 19.1681 - managed by Mercurial (stored in <filename 19.1682 - role="special">.hgtags</filename>). 19.1683 - </para> 19.1684 - </listitem> 19.1685 - <listitem><para id="x_2c2"><literal>node</literal>: A changeset ID. The 19.1686 - ID of the changeset to be tagged. 19.1687 - </para> 19.1688 - </listitem> 19.1689 - <listitem><para id="x_2c3"><literal>tag</literal>: A string. The name of 19.1690 - the tag to be created. 19.1691 - </para> 19.1692 - </listitem></itemizedlist> 19.1693 - 19.1694 - <para id="x_2c4">If the tag to be created is 19.1695 - revision-controlled, the <literal 19.1696 - role="hook">precommit</literal> and <literal 19.1697 - role="hook">pretxncommit</literal> hooks (<xref 19.1698 - linkend="sec:hook:commit"/> and <xref 19.1699 - linkend="sec:hook:pretxncommit"/>) will also be run. 19.1700 - </para> 19.1701 - 19.1702 - <para id="x_2c5">See also: <literal role="hook">tag</literal> 19.1703 - (<xref linkend="sec:hook:tag"/>) 19.1704 - </para> 19.1705 - </sect2> 19.1706 - 19.1707 - <sect2 id="sec:hook:pretxnchangegroup"> 19.1708 - <title><literal 19.1709 - role="hook">pretxnchangegroup</literal>&emdash;before 19.1710 - completing addition of remote changesets</title> 19.1711 - 19.1712 - <para id="x_2c6">This controlling hook is run before a 19.1713 - transaction&emdash;that manages the addition of a group of new 19.1714 - changesets from outside the repository&emdash;completes. If 19.1715 - the hook succeeds, the transaction completes, and all of the 19.1716 - changesets become permanent within this repository. If the 19.1717 - hook fails, the transaction is rolled back, and the data for 19.1718 - the changesets is erased. 19.1719 - </para> 19.1720 - 19.1721 - <para id="x_2c7">This hook can access the metadata associated with the 19.1722 - almost-added changesets, but it should not do anything 19.1723 - permanent with this data. It must also not modify the working 19.1724 - directory. 19.1725 - </para> 19.1726 - 19.1727 - <para id="x_2c8">While this hook is running, if other Mercurial processes 19.1728 - access this repository, they will be able to see the 19.1729 - almost-added changesets as if they are permanent. This may 19.1730 - lead to race conditions if you do not take steps to avoid 19.1731 - them. 19.1732 - </para> 19.1733 - 19.1734 - <para id="x_2c9">This hook can be used to automatically vet a group of 19.1735 - changesets. If the hook fails, all of the changesets are 19.1736 - <quote>rejected</quote> when the transaction rolls back. 19.1737 - </para> 19.1738 - 19.1739 - <para id="x_2ca">Parameters to this hook: 19.1740 - </para> 19.1741 - <itemizedlist> 19.1742 - <listitem><para id="x_2cb"><literal>node</literal>: A changeset ID. The 19.1743 - changeset ID of the first changeset in the group that was 19.1744 - added. All changesets between this and 19.1745 - <literal role="tag">tip</literal>, 19.1746 - inclusive, were added by a single <command 19.1747 - role="hg-cmd">hg pull</command>, <command 19.1748 - role="hg-cmd">hg push</command> or <command 19.1749 - role="hg-cmd">hg unbundle</command>. 19.1750 - </para> 19.1751 - </listitem> 19.1752 - <listitem><para id="x_2cc"><literal>source</literal>: A 19.1753 - string. The source of these changes. See <xref 19.1754 - linkend="sec:hook:sources"/> for details. 19.1755 - </para> 19.1756 - </listitem> 19.1757 - <listitem><para id="x_2cd"><literal>url</literal>: A URL. The 19.1758 - location of the remote repository, if known. See <xref 19.1759 - linkend="sec:hook:url"/> for more information. 19.1760 - </para> 19.1761 - </listitem></itemizedlist> 19.1762 - 19.1763 - <para id="x_2ce">See also: <literal 19.1764 - role="hook">changegroup</literal> (<xref 19.1765 - linkend="sec:hook:changegroup"/>), <literal 19.1766 - role="hook">incoming</literal> (<xref 19.1767 - linkend="sec:hook:incoming"/>), <literal 19.1768 - role="hook">prechangegroup</literal> (<xref 19.1769 - linkend="sec:hook:prechangegroup"/>) 19.1770 - </para> 19.1771 - </sect2> 19.1772 - 19.1773 - <sect2 id="sec:hook:pretxncommit"> 19.1774 - <title><literal role="hook">pretxncommit</literal>&emdash;before 19.1775 - completing commit of new changeset</title> 19.1776 - 19.1777 - <para id="x_2cf">This controlling hook is run before a 19.1778 - transaction&emdash;that manages a new commit&emdash;completes. 19.1779 - If the hook succeeds, the transaction completes and the 19.1780 - changeset becomes permanent within this repository. If the 19.1781 - hook fails, the transaction is rolled back, and the commit 19.1782 - data is erased. 19.1783 - </para> 19.1784 - 19.1785 - <para id="x_2d0">This hook can access the metadata associated with the 19.1786 - almost-new changeset, but it should not do anything permanent 19.1787 - with this data. It must also not modify the working 19.1788 - directory. 19.1789 - </para> 19.1790 - 19.1791 - <para id="x_2d1">While this hook is running, if other Mercurial processes 19.1792 - access this repository, they will be able to see the 19.1793 - almost-new changeset as if it is permanent. This may lead to 19.1794 - race conditions if you do not take steps to avoid them. 19.1795 - </para> 19.1796 - 19.1797 - <para id="x_2d2">Parameters to this hook:</para> 19.1798 - 19.1799 - <itemizedlist> 19.1800 - <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The 19.1801 - changeset ID of the newly committed changeset. 19.1802 - </para> 19.1803 - </listitem> 19.1804 - <listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID. 19.1805 - The changeset ID of the first parent of the newly 19.1806 - committed changeset. 19.1807 - </para> 19.1808 - </listitem> 19.1809 - <listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID. 19.1810 - The changeset ID of the second parent of the newly 19.1811 - committed changeset. 19.1812 - </para> 19.1813 - </listitem></itemizedlist> 19.1814 - 19.1815 - <para id="x_2d6">See also: <literal 19.1816 - role="hook">precommit</literal> (<xref 19.1817 - linkend="sec:hook:precommit"/>) 19.1818 - </para> 19.1819 - </sect2> 19.1820 - 19.1821 - <sect2 id="sec:hook:preupdate"> 19.1822 - <title><literal role="hook">preupdate</literal>&emdash;before 19.1823 - updating or merging working directory</title> 19.1824 - 19.1825 - <para id="x_2d7">This controlling hook is run before an update 19.1826 - or merge of the working directory begins. It is run only if 19.1827 - Mercurial's normal pre-update checks determine that the update 19.1828 - or merge can proceed. If the hook succeeds, the update or 19.1829 - merge may proceed; if it fails, the update or merge does not 19.1830 - start. 19.1831 - </para> 19.1832 - 19.1833 - <para id="x_2d8">Parameters to this hook: 19.1834 - </para> 19.1835 - <itemizedlist> 19.1836 - <listitem><para id="x_2d9"><literal>parent1</literal>: A 19.1837 - changeset ID. The ID of the parent that the working 19.1838 - directory is to be updated to. If the working directory 19.1839 - is being merged, it will not change this parent. 19.1840 - </para> 19.1841 - </listitem> 19.1842 - <listitem><para id="x_2da"><literal>parent2</literal>: A 19.1843 - changeset ID. Only set if the working directory is being 19.1844 - merged. The ID of the revision that the working directory 19.1845 - is being merged with. 19.1846 - </para> 19.1847 - </listitem></itemizedlist> 19.1848 - 19.1849 - <para id="x_2db">See also: <literal role="hook">update</literal> 19.1850 - (<xref linkend="sec:hook:update"/>)</para> 19.1851 - </sect2> 19.1852 - 19.1853 - <sect2 id="sec:hook:tag"> 19.1854 - <title><literal role="hook">tag</literal>&emdash;after tagging a 19.1855 - changeset</title> 19.1856 - 19.1857 - <para id="x_2dc">This hook is run after a tag has been created. 19.1858 - </para> 19.1859 - 19.1860 - <para id="x_2dd">Parameters to this hook: 19.1861 - </para> 19.1862 - <itemizedlist> 19.1863 - <listitem><para id="x_2de"><literal>local</literal>: A boolean. Whether 19.1864 - the new tag is local to this repository instance (i.e. 19.1865 - stored in <filename 19.1866 - role="special">.hg/localtags</filename>) or managed by 19.1867 - Mercurial (stored in <filename 19.1868 - role="special">.hgtags</filename>). 19.1869 - </para> 19.1870 - </listitem> 19.1871 - <listitem><para id="x_2df"><literal>node</literal>: A changeset ID. The 19.1872 - ID of the changeset that was tagged. 19.1873 - </para> 19.1874 - </listitem> 19.1875 - <listitem><para id="x_2e0"><literal>tag</literal>: A string. The name of 19.1876 - the tag that was created. 19.1877 - </para> 19.1878 - </listitem></itemizedlist> 19.1879 - 19.1880 - <para id="x_2e1">If the created tag is revision-controlled, the <literal 19.1881 - role="hook">commit</literal> hook (section <xref 19.1882 - linkend="sec:hook:commit"/>) is run before this hook. 19.1883 - </para> 19.1884 - 19.1885 - <para id="x_2e2">See also: <literal role="hook">pretag</literal> 19.1886 - (<xref linkend="sec:hook:pretag"/>) 19.1887 - </para> 19.1888 - </sect2> 19.1889 - 19.1890 - <sect2 id="sec:hook:update"> 19.1891 - <title><literal role="hook">update</literal>&emdash;after 19.1892 - updating or merging working directory</title> 19.1893 - 19.1894 - <para id="x_2e3">This hook is run after an update or merge of the working 19.1895 - directory completes. Since a merge can fail (if the external 19.1896 - <command>hgmerge</command> command fails to resolve conflicts 19.1897 - in a file), this hook communicates whether the update or merge 19.1898 - completed cleanly. 19.1899 - </para> 19.1900 - 19.1901 - <itemizedlist> 19.1902 - <listitem><para id="x_2e4"><literal>error</literal>: A boolean. 19.1903 - Indicates whether the update or merge completed 19.1904 - successfully. 19.1905 - </para> 19.1906 - </listitem> 19.1907 - <listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID. 19.1908 - The ID of the parent that the working directory was 19.1909 - updated to. If the working directory was merged, it will 19.1910 - not have changed this parent. 19.1911 - </para> 19.1912 - </listitem> 19.1913 - <listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID. 19.1914 - Only set if the working directory was merged. The ID of 19.1915 - the revision that the working directory was merged with. 19.1916 - </para> 19.1917 - </listitem></itemizedlist> 19.1918 - 19.1919 - <para id="x_2e7">See also: <literal role="hook">preupdate</literal> 19.1920 - (<xref linkend="sec:hook:preupdate"/>) 19.1921 - </para> 19.1922 - 19.1923 - </sect2> 19.1924 - </sect1> 19.1925 -</chapter> 19.1926 - 19.1927 -<!-- 19.1928 -local variables: 19.1929 -sgml-parent-document: ("00book.xml" "book" "chapter") 19.1930 -end: 19.1931 --->
20.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 20.2 +++ b/en/ch09-undo.xml Thu May 07 21:07:35 2009 -0700 20.3 @@ -0,0 +1,1201 @@ 20.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 20.5 + 20.6 +<chapter id="chap:undo"> 20.7 + <?dbhtml filename="finding-and-fixing-mistakes.html"?> 20.8 + <title>Finding and fixing mistakes</title> 20.9 + 20.10 + <para id="x_d2">To err might be human, but to really handle the consequences 20.11 + well takes a top-notch revision control system. In this chapter, 20.12 + we'll discuss some of the techniques you can use when you find 20.13 + that a problem has crept into your project. Mercurial has some 20.14 + highly capable features that will help you to isolate the sources 20.15 + of problems, and to handle them appropriately.</para> 20.16 + 20.17 + <sect1> 20.18 + <title>Erasing local history</title> 20.19 + 20.20 + <sect2> 20.21 + <title>The accidental commit</title> 20.22 + 20.23 + <para id="x_d3">I have the occasional but persistent problem of typing 20.24 + rather more quickly than I can think, which sometimes results 20.25 + in me committing a changeset that is either incomplete or 20.26 + plain wrong. In my case, the usual kind of incomplete 20.27 + changeset is one in which I've created a new source file, but 20.28 + forgotten to <command role="hg-cmd">hg add</command> it. A 20.29 + <quote>plain wrong</quote> changeset is not as common, but no 20.30 + less annoying.</para> 20.31 + 20.32 + </sect2> 20.33 + <sect2 id="sec:undo:rollback"> 20.34 + <title>Rolling back a transaction</title> 20.35 + 20.36 + <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I 20.37 + mentioned that Mercurial treats each modification of a 20.38 + repository as a <emphasis>transaction</emphasis>. Every time 20.39 + you commit a changeset or pull changes from another 20.40 + repository, Mercurial remembers what you did. You can undo, 20.41 + or <emphasis>roll back</emphasis>, exactly one of these 20.42 + actions using the <command role="hg-cmd">hg rollback</command> 20.43 + command. (See <xref linkend="sec:undo:rollback-after-push"/> 20.44 + for an important caveat about the use of this command.)</para> 20.45 + 20.46 + <para id="x_d5">Here's a mistake that I often find myself making: 20.47 + committing a change in which I've created a new file, but 20.48 + forgotten to <command role="hg-cmd">hg add</command> 20.49 + it.</para> 20.50 + 20.51 + &interaction.rollback.commit; 20.52 + 20.53 + <para id="x_d6">Looking at the output of <command role="hg-cmd">hg 20.54 + status</command> after the commit immediately confirms the 20.55 + error.</para> 20.56 + 20.57 + &interaction.rollback.status; 20.58 + 20.59 + <para id="x_d7">The commit captured the changes to the file 20.60 + <filename>a</filename>, but not the new file 20.61 + <filename>b</filename>. If I were to push this changeset to a 20.62 + repository that I shared with a colleague, the chances are 20.63 + high that something in <filename>a</filename> would refer to 20.64 + <filename>b</filename>, which would not be present in their 20.65 + repository when they pulled my changes. I would thus become 20.66 + the object of some indignation.</para> 20.67 + 20.68 + <para id="x_d8">However, luck is with me&emdash;I've caught my error 20.69 + before I pushed the changeset. I use the <command 20.70 + role="hg-cmd">hg rollback</command> command, and Mercurial 20.71 + makes that last changeset vanish.</para> 20.72 + 20.73 + &interaction.rollback.rollback; 20.74 + 20.75 + <para id="x_d9">Notice that the changeset is no longer present in the 20.76 + repository's history, and the working directory once again 20.77 + thinks that the file <filename>a</filename> is modified. The 20.78 + commit and rollback have left the working directory exactly as 20.79 + it was prior to the commit; the changeset has been completely 20.80 + erased. I can now safely <command role="hg-cmd">hg 20.81 + add</command> the file <filename>b</filename>, and rerun my 20.82 + commit.</para> 20.83 + 20.84 + &interaction.rollback.add; 20.85 + 20.86 + </sect2> 20.87 + <sect2> 20.88 + <title>The erroneous pull</title> 20.89 + 20.90 + <para id="x_da">It's common practice with Mercurial to maintain separate 20.91 + development branches of a project in different repositories. 20.92 + Your development team might have one shared repository for 20.93 + your project's <quote>0.9</quote> release, and another, 20.94 + containing different changes, for the <quote>1.0</quote> 20.95 + release.</para> 20.96 + 20.97 + <para id="x_db">Given this, you can imagine that the consequences could be 20.98 + messy if you had a local <quote>0.9</quote> repository, and 20.99 + accidentally pulled changes from the shared <quote>1.0</quote> 20.100 + repository into it. At worst, you could be paying 20.101 + insufficient attention, and push those changes into the shared 20.102 + <quote>0.9</quote> tree, confusing your entire team (but don't 20.103 + worry, we'll return to this horror scenario later). However, 20.104 + it's more likely that you'll notice immediately, because 20.105 + Mercurial will display the URL it's pulling from, or you will 20.106 + see it pull a suspiciously large number of changes into the 20.107 + repository.</para> 20.108 + 20.109 + <para id="x_dc">The <command role="hg-cmd">hg rollback</command> command 20.110 + will work nicely to expunge all of the changesets that you 20.111 + just pulled. Mercurial groups all changes from one <command 20.112 + role="hg-cmd">hg pull</command> into a single transaction, 20.113 + so one <command role="hg-cmd">hg rollback</command> is all you 20.114 + need to undo this mistake.</para> 20.115 + 20.116 + </sect2> 20.117 + <sect2 id="sec:undo:rollback-after-push"> 20.118 + <title>Rolling back is useless once you've pushed</title> 20.119 + 20.120 + <para id="x_dd">The value of the <command role="hg-cmd">hg 20.121 + rollback</command> command drops to zero once you've pushed 20.122 + your changes to another repository. Rolling back a change 20.123 + makes it disappear entirely, but <emphasis>only</emphasis> in 20.124 + the repository in which you perform the <command 20.125 + role="hg-cmd">hg rollback</command>. Because a rollback 20.126 + eliminates history, there's no way for the disappearance of a 20.127 + change to propagate between repositories.</para> 20.128 + 20.129 + <para id="x_de">If you've pushed a change to another 20.130 + repository&emdash;particularly if it's a shared 20.131 + repository&emdash;it has essentially <quote>escaped into the 20.132 + wild,</quote> and you'll have to recover from your mistake 20.133 + in a different way. If you push a changeset somewhere, then 20.134 + roll it back, then pull from the repository you pushed to, the 20.135 + changeset you thought you'd gotten rid of will simply reappear 20.136 + in your repository.</para> 20.137 + 20.138 + <para id="x_df">(If you absolutely know for sure that the change 20.139 + you want to roll back is the most recent change in the 20.140 + repository that you pushed to, <emphasis>and</emphasis> you 20.141 + know that nobody else could have pulled it from that 20.142 + repository, you can roll back the changeset there, too, but 20.143 + you really should not expect this to work reliably. Sooner or 20.144 + later a change really will make it into a repository that you 20.145 + don't directly control (or have forgotten about), and come 20.146 + back to bite you.)</para> 20.147 + 20.148 + </sect2> 20.149 + <sect2> 20.150 + <title>You can only roll back once</title> 20.151 + 20.152 + <para id="x_e0">Mercurial stores exactly one transaction in its 20.153 + transaction log; that transaction is the most recent one that 20.154 + occurred in the repository. This means that you can only roll 20.155 + back one transaction. If you expect to be able to roll back 20.156 + one transaction, then its predecessor, this is not the 20.157 + behavior you will get.</para> 20.158 + 20.159 + &interaction.rollback.twice; 20.160 + 20.161 + <para id="x_e1">Once you've rolled back one transaction in a repository, 20.162 + you can't roll back again in that repository until you perform 20.163 + another commit or pull.</para> 20.164 + 20.165 + </sect2> 20.166 + </sect1> 20.167 + <sect1> 20.168 + <title>Reverting the mistaken change</title> 20.169 + 20.170 + <para id="x_e2">If you make a modification to a file, and decide that you 20.171 + really didn't want to change the file at all, and you haven't 20.172 + yet committed your changes, the <command role="hg-cmd">hg 20.173 + revert</command> command is the one you'll need. It looks at 20.174 + the changeset that's the parent of the working directory, and 20.175 + restores the contents of the file to their state as of that 20.176 + changeset. (That's a long-winded way of saying that, in the 20.177 + normal case, it undoes your modifications.)</para> 20.178 + 20.179 + <para id="x_e3">Let's illustrate how the <command role="hg-cmd">hg 20.180 + revert</command> command works with yet another small example. 20.181 + We'll begin by modifying a file that Mercurial is already 20.182 + tracking.</para> 20.183 + 20.184 + &interaction.daily.revert.modify; 20.185 + 20.186 + <para id="x_e4">If we don't 20.187 + want that change, we can simply <command role="hg-cmd">hg 20.188 + revert</command> the file.</para> 20.189 + 20.190 + &interaction.daily.revert.unmodify; 20.191 + 20.192 + <para id="x_e5">The <command role="hg-cmd">hg revert</command> command 20.193 + provides us with an extra degree of safety by saving our 20.194 + modified file with a <filename>.orig</filename> 20.195 + extension.</para> 20.196 + 20.197 + &interaction.daily.revert.status; 20.198 + 20.199 + <tip> 20.200 + <title>Be careful with <filename>.orig</filename> files</title> 20.201 + 20.202 + <para id="x_6b8">It's extremely unlikely that you are either using 20.203 + Mercurial to manage files with <filename>.orig</filename> 20.204 + extensions or that you even care about the contents of such 20.205 + files. Just in case, though, it's useful to remember that 20.206 + <command role="hg-cmd">hg revert</command> will 20.207 + unconditionally overwrite an existing file with a 20.208 + <filename>.orig</filename> extension. For instance, if you 20.209 + already have a file named <filename>foo.orig</filename> when 20.210 + you revert <filename>foo</filename>, the contents of 20.211 + <filename>foo.orig</filename> will be clobbered.</para> 20.212 + </tip> 20.213 + 20.214 + <para id="x_e6">Here is a summary of the cases that the <command 20.215 + role="hg-cmd">hg revert</command> command can deal with. We 20.216 + will describe each of these in more detail in the section that 20.217 + follows.</para> 20.218 + <itemizedlist> 20.219 + <listitem><para id="x_e7">If you modify a file, it will restore the file 20.220 + to its unmodified state.</para> 20.221 + </listitem> 20.222 + <listitem><para id="x_e8">If you <command role="hg-cmd">hg add</command> a 20.223 + file, it will undo the <quote>added</quote> state of the 20.224 + file, but leave the file itself untouched.</para> 20.225 + </listitem> 20.226 + <listitem><para id="x_e9">If you delete a file without telling Mercurial, 20.227 + it will restore the file to its unmodified contents.</para> 20.228 + </listitem> 20.229 + <listitem><para id="x_ea">If you use the <command role="hg-cmd">hg 20.230 + remove</command> command to remove a file, it will undo 20.231 + the <quote>removed</quote> state of the file, and restore 20.232 + the file to its unmodified contents.</para> 20.233 + </listitem></itemizedlist> 20.234 + 20.235 + <sect2 id="sec:undo:mgmt"> 20.236 + <title>File management errors</title> 20.237 + 20.238 + <para id="x_eb">The <command role="hg-cmd">hg revert</command> command is 20.239 + useful for more than just modified files. It lets you reverse 20.240 + the results of all of Mercurial's file management 20.241 + commands&emdash;<command role="hg-cmd">hg add</command>, 20.242 + <command role="hg-cmd">hg remove</command>, and so on.</para> 20.243 + 20.244 + <para id="x_ec">If you <command role="hg-cmd">hg add</command> a file, 20.245 + then decide that in fact you don't want Mercurial to track it, 20.246 + use <command role="hg-cmd">hg revert</command> to undo the 20.247 + add. Don't worry; Mercurial will not modify the file in any 20.248 + way. It will just <quote>unmark</quote> the file.</para> 20.249 + 20.250 + &interaction.daily.revert.add; 20.251 + 20.252 + <para id="x_ed">Similarly, if you ask Mercurial to <command 20.253 + role="hg-cmd">hg remove</command> a file, you can use 20.254 + <command role="hg-cmd">hg revert</command> to restore it to 20.255 + the contents it had as of the parent of the working directory. 20.256 + &interaction.daily.revert.remove; This works just as 20.257 + well for a file that you deleted by hand, without telling 20.258 + Mercurial (recall that in Mercurial terminology, this kind of 20.259 + file is called <quote>missing</quote>).</para> 20.260 + 20.261 + &interaction.daily.revert.missing; 20.262 + 20.263 + <para id="x_ee">If you revert a <command role="hg-cmd">hg copy</command>, 20.264 + the copied-to file remains in your working directory 20.265 + afterwards, untracked. Since a copy doesn't affect the 20.266 + copied-from file in any way, Mercurial doesn't do anything 20.267 + with the copied-from file.</para> 20.268 + 20.269 + &interaction.daily.revert.copy; 20.270 + </sect2> 20.271 + </sect1> 20.272 + 20.273 + <sect1> 20.274 + <title>Dealing with committed changes</title> 20.275 + 20.276 + <para id="x_f5">Consider a case where you have committed a change 20.277 + <emphasis>a</emphasis>, and another change 20.278 + <emphasis>b</emphasis> on top of it; you then realise that 20.279 + change <emphasis>a</emphasis> was incorrect. Mercurial lets you 20.280 + <quote>back out</quote> an entire changeset automatically, and 20.281 + building blocks that let you reverse part of a changeset by 20.282 + hand.</para> 20.283 + 20.284 + <para id="x_f6">Before you read this section, here's something to 20.285 + keep in mind: the <command role="hg-cmd">hg backout</command> 20.286 + command undoes the effect of a change by 20.287 + <emphasis>adding</emphasis> to your repository's history, not by 20.288 + modifying or erasing it. It's the right tool to use if you're 20.289 + fixing bugs, but not if you're trying to undo some change that 20.290 + has catastrophic consequences. To deal with those, see 20.291 + <xref linkend="sec:undo:aaaiiieee"/>.</para> 20.292 + 20.293 + <sect2> 20.294 + <title>Backing out a changeset</title> 20.295 + 20.296 + <para id="x_f7">The <command role="hg-cmd">hg backout</command> command 20.297 + lets you <quote>undo</quote> the effects of an entire 20.298 + changeset in an automated fashion. Because Mercurial's 20.299 + history is immutable, this command <emphasis>does 20.300 + not</emphasis> get rid of the changeset you want to undo. 20.301 + Instead, it creates a new changeset that 20.302 + <emphasis>reverses</emphasis> the effect of the to-be-undone 20.303 + changeset.</para> 20.304 + 20.305 + <para id="x_f8">The operation of the <command role="hg-cmd">hg 20.306 + backout</command> command is a little intricate, so let's 20.307 + illustrate it with some examples. First, we'll create a 20.308 + repository with some simple changes.</para> 20.309 + 20.310 + &interaction.backout.init; 20.311 + 20.312 + <para id="x_f9">The <command role="hg-cmd">hg backout</command> command 20.313 + takes a single changeset ID as its argument; this is the 20.314 + changeset to back out. Normally, <command role="hg-cmd">hg 20.315 + backout</command> will drop you into a text editor to write 20.316 + a commit message, so you can record why you're backing the 20.317 + change out. In this example, we provide a commit message on 20.318 + the command line using the <option 20.319 + role="hg-opt-backout">-m</option> option.</para> 20.320 + 20.321 + </sect2> 20.322 + <sect2> 20.323 + <title>Backing out the tip changeset</title> 20.324 + 20.325 + <para id="x_fa">We're going to start by backing out the last changeset we 20.326 + committed.</para> 20.327 + 20.328 + &interaction.backout.simple; 20.329 + 20.330 + <para id="x_fb">You can see that the second line from 20.331 + <filename>myfile</filename> is no longer present. Taking a 20.332 + look at the output of <command role="hg-cmd">hg log</command> 20.333 + gives us an idea of what the <command role="hg-cmd">hg 20.334 + backout</command> command has done. 20.335 + &interaction.backout.simple.log; Notice that the new changeset 20.336 + that <command role="hg-cmd">hg backout</command> has created 20.337 + is a child of the changeset we backed out. It's easier to see 20.338 + this in <xref linkend="fig:undo:backout"/>, which presents a 20.339 + graphical view of the change history. As you can see, the 20.340 + history is nice and linear.</para> 20.341 + 20.342 + <figure id="fig:undo:backout"> 20.343 + <title>Backing out a change using the <command 20.344 + role="hg-cmd">hg backout</command> command</title> 20.345 + <mediaobject> 20.346 + <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject> 20.347 + <textobject><phrase>XXX add text</phrase></textobject> 20.348 + </mediaobject> 20.349 + </figure> 20.350 + 20.351 + </sect2> 20.352 + <sect2> 20.353 + <title>Backing out a non-tip change</title> 20.354 + 20.355 + <para id="x_fd">If you want to back out a change other than the last one 20.356 + you committed, pass the <option 20.357 + role="hg-opt-backout">--merge</option> option to the 20.358 + <command role="hg-cmd">hg backout</command> command.</para> 20.359 + 20.360 + &interaction.backout.non-tip.clone; 20.361 + 20.362 + <para id="x_fe">This makes backing out any changeset a 20.363 + <quote>one-shot</quote> operation that's usually simple and 20.364 + fast.</para> 20.365 + 20.366 + &interaction.backout.non-tip.backout; 20.367 + 20.368 + <para id="x_ff">If you take a look at the contents of 20.369 + <filename>myfile</filename> after the backout finishes, you'll 20.370 + see that the first and third changes are present, but not the 20.371 + second.</para> 20.372 + 20.373 + &interaction.backout.non-tip.cat; 20.374 + 20.375 + <para id="x_100">As the graphical history in <xref 20.376 + linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial 20.377 + still commits one change in this kind of situation (the 20.378 + box-shaped node is the ones that Mercurial commits 20.379 + automatically), but the revision graph now looks different. 20.380 + Before Mercurial begins the backout process, it first 20.381 + remembers what the current parent of the working directory is. 20.382 + It then backs out the target changeset, and commits that as a 20.383 + changeset. Finally, it merges back to the previous parent of 20.384 + the working directory, but notice that it <emphasis>does not 20.385 + commit</emphasis> the result of the merge. The repository 20.386 + now contains two heads, and the working directory is in a 20.387 + merge state.</para> 20.388 + 20.389 + <figure id="fig:undo:backout-non-tip"> 20.390 + <title>Automated backout of a non-tip change using the 20.391 + <command role="hg-cmd">hg backout</command> command</title> 20.392 + <mediaobject> 20.393 + <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject> 20.394 + <textobject><phrase>XXX add text</phrase></textobject> 20.395 + </mediaobject> 20.396 + </figure> 20.397 + 20.398 + <para id="x_103">The result is that you end up <quote>back where you 20.399 + were</quote>, only with some extra history that undoes the 20.400 + effect of the changeset you wanted to back out.</para> 20.401 + 20.402 + <para id="x_6b9">You might wonder why Mercurial does not commit the result 20.403 + of the merge that it performed. The reason lies in Mercurial 20.404 + behaving conservatively: a merge naturally has more scope for 20.405 + error than simply undoing the effect of the tip changeset, 20.406 + so your work will be safest if you first inspect (and test!) 20.407 + the result of the merge, <emphasis>then</emphasis> commit 20.408 + it.</para> 20.409 + 20.410 + <sect3> 20.411 + <title>Always use the <option 20.412 + role="hg-opt-backout">--merge</option> option</title> 20.413 + 20.414 + <para id="x_104">In fact, since the <option 20.415 + role="hg-opt-backout">--merge</option> option will do the 20.416 + <quote>right thing</quote> whether or not the changeset 20.417 + you're backing out is the tip (i.e. it won't try to merge if 20.418 + it's backing out the tip, since there's no need), you should 20.419 + <emphasis>always</emphasis> use this option when you run the 20.420 + <command role="hg-cmd">hg backout</command> command.</para> 20.421 + 20.422 + </sect3> 20.423 + </sect2> 20.424 + <sect2> 20.425 + <title>Gaining more control of the backout process</title> 20.426 + 20.427 + <para id="x_105">While I've recommended that you always use the <option 20.428 + role="hg-opt-backout">--merge</option> option when backing 20.429 + out a change, the <command role="hg-cmd">hg backout</command> 20.430 + command lets you decide how to merge a backout changeset. 20.431 + Taking control of the backout process by hand is something you 20.432 + will rarely need to do, but it can be useful to understand 20.433 + what the <command role="hg-cmd">hg backout</command> command 20.434 + is doing for you automatically. To illustrate this, let's 20.435 + clone our first repository, but omit the backout change that 20.436 + it contains.</para> 20.437 + 20.438 + &interaction.backout.manual.clone; 20.439 + 20.440 + <para id="x_106">As with our 20.441 + earlier example, We'll commit a third changeset, then back out 20.442 + its parent, and see what happens.</para> 20.443 + 20.444 + &interaction.backout.manual.backout; 20.445 + 20.446 + <para id="x_107">Our new changeset is again a descendant of the changeset 20.447 + we backout out; it's thus a new head, <emphasis>not</emphasis> 20.448 + a descendant of the changeset that was the tip. The <command 20.449 + role="hg-cmd">hg backout</command> command was quite 20.450 + explicit in telling us this.</para> 20.451 + 20.452 + &interaction.backout.manual.log; 20.453 + 20.454 + <para id="x_108">Again, it's easier to see what has happened by looking at 20.455 + a graph of the revision history, in <xref 20.456 + linkend="fig:undo:backout-manual"/>. This makes it clear 20.457 + that when we use <command role="hg-cmd">hg backout</command> 20.458 + to back out a change other than the tip, Mercurial adds a new 20.459 + head to the repository (the change it committed is 20.460 + box-shaped).</para> 20.461 + 20.462 + <figure id="fig:undo:backout-manual"> 20.463 + <title>Backing out a change using the <command 20.464 + role="hg-cmd">hg backout</command> command</title> 20.465 + <mediaobject> 20.466 + <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject> 20.467 + <textobject><phrase>XXX add text</phrase></textobject> 20.468 + </mediaobject> 20.469 + </figure> 20.470 + 20.471 + <para id="x_10a">After the <command role="hg-cmd">hg backout</command> 20.472 + command has completed, it leaves the new 20.473 + <quote>backout</quote> changeset as the parent of the working 20.474 + directory.</para> 20.475 + 20.476 + &interaction.backout.manual.parents; 20.477 + 20.478 + <para id="x_10b">Now we have two isolated sets of changes.</para> 20.479 + 20.480 + &interaction.backout.manual.heads; 20.481 + 20.482 + <para id="x_10c">Let's think about what we expect to see as the contents of 20.483 + <filename>myfile</filename> now. The first change should be 20.484 + present, because we've never backed it out. The second change 20.485 + should be missing, as that's the change we backed out. Since 20.486 + the history graph shows the third change as a separate head, 20.487 + we <emphasis>don't</emphasis> expect to see the third change 20.488 + present in <filename>myfile</filename>.</para> 20.489 + 20.490 + &interaction.backout.manual.cat; 20.491 + 20.492 + <para id="x_10d">To get the third change back into the file, we just do a 20.493 + normal merge of our two heads.</para> 20.494 + 20.495 + &interaction.backout.manual.merge; 20.496 + 20.497 + <para id="x_10e">Afterwards, the graphical history of our 20.498 + repository looks like 20.499 + <xref linkend="fig:undo:backout-manual-merge"/>.</para> 20.500 + 20.501 + <figure id="fig:undo:backout-manual-merge"> 20.502 + <title>Manually merging a backout change</title> 20.503 + <mediaobject> 20.504 + <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject> 20.505 + <textobject><phrase>XXX add text</phrase></textobject> 20.506 + </mediaobject> 20.507 + </figure> 20.508 + 20.509 + </sect2> 20.510 + <sect2> 20.511 + <title>Why <command role="hg-cmd">hg backout</command> works as 20.512 + it does</title> 20.513 + 20.514 + <para id="x_110">Here's a brief description of how the <command 20.515 + role="hg-cmd">hg backout</command> command works.</para> 20.516 + <orderedlist> 20.517 + <listitem><para id="x_111">It ensures that the working directory is 20.518 + <quote>clean</quote>, i.e. that the output of <command 20.519 + role="hg-cmd">hg status</command> would be empty.</para> 20.520 + </listitem> 20.521 + <listitem><para id="x_112">It remembers the current parent of the working 20.522 + directory. Let's call this changeset 20.523 + <literal>orig</literal>.</para> 20.524 + </listitem> 20.525 + <listitem><para id="x_113">It does the equivalent of a <command 20.526 + role="hg-cmd">hg update</command> to sync the working 20.527 + directory to the changeset you want to back out. Let's 20.528 + call this changeset <literal>backout</literal>.</para> 20.529 + </listitem> 20.530 + <listitem><para id="x_114">It finds the parent of that changeset. Let's 20.531 + call that changeset <literal>parent</literal>.</para> 20.532 + </listitem> 20.533 + <listitem><para id="x_115">For each file that the 20.534 + <literal>backout</literal> changeset affected, it does the 20.535 + equivalent of a <command role="hg-cmd">hg revert -r 20.536 + parent</command> on that file, to restore it to the 20.537 + contents it had before that changeset was 20.538 + committed.</para> 20.539 + </listitem> 20.540 + <listitem><para id="x_116">It commits the result as a new changeset. 20.541 + This changeset has <literal>backout</literal> as its 20.542 + parent.</para> 20.543 + </listitem> 20.544 + <listitem><para id="x_117">If you specify <option 20.545 + role="hg-opt-backout">--merge</option> on the command 20.546 + line, it merges with <literal>orig</literal>, and commits 20.547 + the result of the merge.</para> 20.548 + </listitem></orderedlist> 20.549 + 20.550 + <para id="x_118">An alternative way to implement the <command 20.551 + role="hg-cmd">hg backout</command> command would be to 20.552 + <command role="hg-cmd">hg export</command> the 20.553 + to-be-backed-out changeset as a diff, then use the <option 20.554 + role="cmd-opt-patch">--reverse</option> option to the 20.555 + <command>patch</command> command to reverse the effect of the 20.556 + change without fiddling with the working directory. This 20.557 + sounds much simpler, but it would not work nearly as 20.558 + well.</para> 20.559 + 20.560 + <para id="x_119">The reason that <command role="hg-cmd">hg 20.561 + backout</command> does an update, a commit, a merge, and 20.562 + another commit is to give the merge machinery the best chance 20.563 + to do a good job when dealing with all the changes 20.564 + <emphasis>between</emphasis> the change you're backing out and 20.565 + the current tip.</para> 20.566 + 20.567 + <para id="x_11a">If you're backing out a changeset that's 100 revisions 20.568 + back in your project's history, the chances that the 20.569 + <command>patch</command> command will be able to apply a 20.570 + reverse diff cleanly are not good, because intervening changes 20.571 + are likely to have <quote>broken the context</quote> that 20.572 + <command>patch</command> uses to determine whether it can 20.573 + apply a patch (if this sounds like gibberish, see <xref 20.574 + linkend="sec:mq:patch"/> for a 20.575 + discussion of the <command>patch</command> command). Also, 20.576 + Mercurial's merge machinery will handle files and directories 20.577 + being renamed, permission changes, and modifications to binary 20.578 + files, none of which <command>patch</command> can deal 20.579 + with.</para> 20.580 + 20.581 + </sect2> 20.582 + </sect1> 20.583 + <sect1 id="sec:undo:aaaiiieee"> 20.584 + <title>Changes that should never have been</title> 20.585 + 20.586 + <para id="x_11b">Most of the time, the <command role="hg-cmd">hg 20.587 + backout</command> command is exactly what you need if you want 20.588 + to undo the effects of a change. It leaves a permanent record 20.589 + of exactly what you did, both when committing the original 20.590 + changeset and when you cleaned up after it.</para> 20.591 + 20.592 + <para id="x_11c">On rare occasions, though, you may find that you've 20.593 + committed a change that really should not be present in the 20.594 + repository at all. For example, it would be very unusual, and 20.595 + usually considered a mistake, to commit a software project's 20.596 + object files as well as its source files. Object files have 20.597 + almost no intrinsic value, and they're <emphasis>big</emphasis>, 20.598 + so they increase the size of the repository and the amount of 20.599 + time it takes to clone or pull changes.</para> 20.600 + 20.601 + <para id="x_11d">Before I discuss the options that you have if you commit a 20.602 + <quote>brown paper bag</quote> change (the kind that's so bad 20.603 + that you want to pull a brown paper bag over your head), let me 20.604 + first discuss some approaches that probably won't work.</para> 20.605 + 20.606 + <para id="x_11e">Since Mercurial treats history as 20.607 + accumulative&emdash;every change builds on top of all changes 20.608 + that preceded it&emdash;you generally can't just make disastrous 20.609 + changes disappear. The one exception is when you've just 20.610 + committed a change, and it hasn't been pushed or pulled into 20.611 + another repository. That's when you can safely use the <command 20.612 + role="hg-cmd">hg rollback</command> command, as I detailed in 20.613 + <xref linkend="sec:undo:rollback"/>.</para> 20.614 + 20.615 + <para id="x_11f">After you've pushed a bad change to another repository, you 20.616 + <emphasis>could</emphasis> still use <command role="hg-cmd">hg 20.617 + rollback</command> to make your local copy of the change 20.618 + disappear, but it won't have the consequences you want. The 20.619 + change will still be present in the remote repository, so it 20.620 + will reappear in your local repository the next time you 20.621 + pull.</para> 20.622 + 20.623 + <para id="x_120">If a situation like this arises, and you know which 20.624 + repositories your bad change has propagated into, you can 20.625 + <emphasis>try</emphasis> to get rid of the change from 20.626 + <emphasis>every</emphasis> one of those repositories. This is, 20.627 + of course, not a satisfactory solution: if you miss even a 20.628 + single repository while you're expunging, the change is still 20.629 + <quote>in the wild</quote>, and could propagate further.</para> 20.630 + 20.631 + <para id="x_121">If you've committed one or more changes 20.632 + <emphasis>after</emphasis> the change that you'd like to see 20.633 + disappear, your options are further reduced. Mercurial doesn't 20.634 + provide a way to <quote>punch a hole</quote> in history, leaving 20.635 + changesets intact.</para> 20.636 + 20.637 + <sect2> 20.638 + <title>Backing out a merge</title> 20.639 + 20.640 + <para id="x_6ba">Since merges are often complicated, it is not unheard of 20.641 + for a merge to be mangled badly, but committed erroneously. 20.642 + Mercurial provides an important safeguard against bad merges 20.643 + by refusing to commit unresolved files, but human ingenuity 20.644 + guarantees that it is still possible to mess a merge up and 20.645 + commit it.</para> 20.646 + 20.647 + <para id="x_6bb">Given a bad merge that has been committed, usually the 20.648 + best way to approach it is to simply try to repair the damage 20.649 + by hand. A complete disaster that cannot be easily fixed up 20.650 + by hand ought to be very rare, but the <command 20.651 + role="hg-cmd">hg backout</command> command may help in 20.652 + making the cleanup easier. It offers a <option 20.653 + role="hg-opt-backout">--parent</option> option, which lets 20.654 + you specify which parent to revert to when backing out a 20.655 + merge.</para> 20.656 + 20.657 + <figure id="fig:undo:bad-merge-1"> 20.658 + <title>A bad merge</title> 20.659 + <mediaobject> 20.660 + <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject> 20.661 + <textobject><phrase>XXX add text</phrase></textobject> 20.662 + </mediaobject> 20.663 + </figure> 20.664 + 20.665 + <para id="x_6bc">Suppose we have a revision graph like that in <xref 20.666 + linkend="fig:undo:bad-merge-1"/>. What we'd like is to 20.667 + <emphasis>redo</emphasis> the merge of revisions 2 and 20.668 + 3.</para> 20.669 + 20.670 + <para id="x_6bd">One way to do so would be as follows.</para> 20.671 + 20.672 + <orderedlist> 20.673 + <listitem> 20.674 + <para id="x_6be">Call <command role="hg-cmd">hg backout --rev=4 20.675 + --parent=2</command>. This tells <command 20.676 + role="hg-cmd">hg backout</command> to back out revision 20.677 + 4, which is the bad merge, and to when deciding which 20.678 + revision to prefer, to choose parent 2, one of the parents 20.679 + of the merge. The effect can be seen in <xref 20.680 + linkend="fig:undo:bad-merge-2"/>.</para> 20.681 + <figure id="fig:undo:bad-merge-2"> 20.682 + <title>Backing out the merge, favoring one parent</title> 20.683 + <mediaobject> 20.684 + <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject> 20.685 + <textobject><phrase>XXX add text</phrase></textobject> 20.686 + </mediaobject> 20.687 + </figure> 20.688 + </listitem> 20.689 + 20.690 + <listitem> 20.691 + <para id="x_6bf">Call <command role="hg-cmd">hg backout --rev=4 20.692 + --parent=3</command>. This tells <command 20.693 + role="hg-cmd">hg backout</command> to back out revision 20.694 + 4 again, but this time to choose parent 3, the other 20.695 + parent of the merge. The result is visible in <xref 20.696 + linkend="fig:undo:bad-merge-3"/>, in which the repository 20.697 + now contains three heads.</para> 20.698 + <figure id="fig:undo:bad-merge-3"> 20.699 + <title>Backing out the merge, favoring the other 20.700 + parent</title> 20.701 + <mediaobject> 20.702 + <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject> 20.703 + <textobject><phrase>XXX add text</phrase></textobject> 20.704 + </mediaobject> 20.705 + </figure> 20.706 + </listitem> 20.707 + 20.708 + <listitem> 20.709 + <para id="x_6c0">Redo the bad merge by merging the two backout heads, 20.710 + which reduces the number of heads in the repository to 20.711 + two, as can be seen in <xref 20.712 + linkend="fig:undo:bad-merge-4"/>.</para> 20.713 + <figure id="fig:undo:bad-merge-4"> 20.714 + <title>Merging the backouts</title> 20.715 + <mediaobject> 20.716 + <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject> 20.717 + <textobject><phrase>XXX add text</phrase></textobject> 20.718 + </mediaobject> 20.719 + </figure> 20.720 + </listitem> 20.721 + 20.722 + <listitem> 20.723 + <para id="x_6c1">Merge with the commit that was made after the bad 20.724 + merge, as shown in <xref 20.725 + linkend="fig:undo:bad-merge-5"/>.</para> 20.726 + <figure id="fig:undo:bad-merge-5"> 20.727 + <title>Merging the backouts</title> 20.728 + <mediaobject> 20.729 + <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject> 20.730 + <textobject><phrase>XXX add text</phrase></textobject> 20.731 + </mediaobject> 20.732 + </figure> 20.733 + </listitem> 20.734 + </orderedlist> 20.735 + </sect2> 20.736 + 20.737 + <sect2> 20.738 + <title>Protect yourself from <quote>escaped</quote> 20.739 + changes</title> 20.740 + 20.741 + <para id="x_123">If you've committed some changes to your local repository 20.742 + and they've been pushed or pulled somewhere else, this isn't 20.743 + necessarily a disaster. You can protect yourself ahead of 20.744 + time against some classes of bad changeset. This is 20.745 + particularly easy if your team usually pulls changes from a 20.746 + central repository.</para> 20.747 + 20.748 + <para id="x_124">By configuring some hooks on that repository to validate 20.749 + incoming changesets (see chapter <xref linkend="chap:hook"/>), 20.750 + you can 20.751 + automatically prevent some kinds of bad changeset from being 20.752 + pushed to the central repository at all. With such a 20.753 + configuration in place, some kinds of bad changeset will 20.754 + naturally tend to <quote>die out</quote> because they can't 20.755 + propagate into the central repository. Better yet, this 20.756 + happens without any need for explicit intervention.</para> 20.757 + 20.758 + <para id="x_125">For instance, an incoming change hook that 20.759 + verifies that a changeset will actually compile can prevent 20.760 + people from inadvertently <quote>breaking the 20.761 + build</quote>.</para> 20.762 + </sect2> 20.763 + 20.764 + <sect2> 20.765 + <title>What to do about sensitive changes that escape</title> 20.766 + 20.767 + <para id="x_6c2">Even a carefully run project can suffer an unfortunate 20.768 + event such as the committing and uncontrolled propagation of a 20.769 + file that contains important passwords.</para> 20.770 + 20.771 + <para id="x_6c3">If something like this happens to you, and the information 20.772 + that gets accidentally propagated is truly sensitive, your 20.773 + first step should be to mitigate the effect of the leak 20.774 + without trying to control the leak itself. If you are not 100% 20.775 + certain that you know exactly who could have seen the changes, 20.776 + you should immediately change passwords, cancel credit cards, 20.777 + or find some other way to make sure that the information that 20.778 + has leaked is no longer useful. In other words, assume that 20.779 + the change has propagated far and wide, and that there's 20.780 + nothing more you can do.</para> 20.781 + 20.782 + <para id="x_6c4">You might hope that there would be mechanisms you could 20.783 + use to either figure out who has seen a change or to erase the 20.784 + change permanently everywhere, but there are good reasons why 20.785 + these are not possible.</para> 20.786 + 20.787 + <para id="x_6c5">Mercurial does not provide an audit trail of who has 20.788 + pulled changes from a repository, because it is usually either 20.789 + impossible to record such information or trivial to spoof it. 20.790 + In a multi-user or networked environment, you should thus be 20.791 + extremely skeptical of yourself if you think that you have 20.792 + identified every place that a sensitive changeset has 20.793 + propagated to. Don't forget that people can and will send 20.794 + bundles by email, have their backup software save data 20.795 + offsite, carry repositories on USB sticks, and find other 20.796 + completely innocent ways to confound your attempts to track 20.797 + down every copy of a problematic change.</para> 20.798 + 20.799 + <para id="x_6c6">Mercurial also does not provide a way to make a file or 20.800 + changeset completely disappear from history, because there is 20.801 + no way to enforce its disappearance; someone could easily 20.802 + modify their copy of Mercurial to ignore such directives. In 20.803 + addition, even if Mercurial provided such a capability, 20.804 + someone who simply hadn't pulled a <quote>make this file 20.805 + disappear</quote> changeset wouldn't be affected by it, nor 20.806 + would web crawlers visiting at the wrong time, disk backups, 20.807 + or other mechanisms. Indeed, no distributed revision control 20.808 + system can make data reliably vanish. Providing the illusion 20.809 + of such control could easily give a false sense of security, 20.810 + and be worse than not providing it at all.</para> 20.811 + </sect2> 20.812 + </sect1> 20.813 + 20.814 + <sect1 id="sec:undo:bisect"> 20.815 + <title>Finding the source of a bug</title> 20.816 + 20.817 + <para id="x_126">While it's all very well to be able to back out a changeset 20.818 + that introduced a bug, this requires that you know which 20.819 + changeset to back out. Mercurial provides an invaluable 20.820 + command, called <command role="hg-cmd">hg bisect</command>, that 20.821 + helps you to automate this process and accomplish it very 20.822 + efficiently.</para> 20.823 + 20.824 + <para id="x_127">The idea behind the <command role="hg-cmd">hg 20.825 + bisect</command> command is that a changeset has introduced 20.826 + some change of behavior that you can identify with a simple 20.827 + pass/fail test. You don't know which piece of code introduced the 20.828 + change, but you know how to test for the presence of the bug. 20.829 + The <command role="hg-cmd">hg bisect</command> command uses your 20.830 + test to direct its search for the changeset that introduced the 20.831 + code that caused the bug.</para> 20.832 + 20.833 + <para id="x_128">Here are a few scenarios to help you understand how you 20.834 + might apply this command.</para> 20.835 + <itemizedlist> 20.836 + <listitem><para id="x_129">The most recent version of your software has a 20.837 + bug that you remember wasn't present a few weeks ago, but 20.838 + you don't know when it was introduced. Here, your binary 20.839 + test checks for the presence of that bug.</para> 20.840 + </listitem> 20.841 + <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to 20.842 + close the entry in your team's bug database. The bug 20.843 + database requires a changeset ID when you close an entry, 20.844 + but you don't remember which changeset you fixed the bug in. 20.845 + Once again, your binary test checks for the presence of the 20.846 + bug.</para> 20.847 + </listitem> 20.848 + <listitem><para id="x_12b">Your software works correctly, but runs 15% 20.849 + slower than the last time you measured it. You want to know 20.850 + which changeset introduced the performance regression. In 20.851 + this case, your binary test measures the performance of your 20.852 + software, to see whether it's <quote>fast</quote> or 20.853 + <quote>slow</quote>.</para> 20.854 + </listitem> 20.855 + <listitem><para id="x_12c">The sizes of the components of your project that 20.856 + you ship exploded recently, and you suspect that something 20.857 + changed in the way you build your project.</para> 20.858 + </listitem></itemizedlist> 20.859 + 20.860 + <para id="x_12d">From these examples, it should be clear that the <command 20.861 + role="hg-cmd">hg bisect</command> command is not useful only 20.862 + for finding the sources of bugs. You can use it to find any 20.863 + <quote>emergent property</quote> of a repository (anything that 20.864 + you can't find from a simple text search of the files in the 20.865 + tree) for which you can write a binary test.</para> 20.866 + 20.867 + <para id="x_12e">We'll introduce a little bit of terminology here, just to 20.868 + make it clear which parts of the search process are your 20.869 + responsibility, and which are Mercurial's. A 20.870 + <emphasis>test</emphasis> is something that 20.871 + <emphasis>you</emphasis> run when <command role="hg-cmd">hg 20.872 + bisect</command> chooses a changeset. A 20.873 + <emphasis>probe</emphasis> is what <command role="hg-cmd">hg 20.874 + bisect</command> runs to tell whether a revision is good. 20.875 + Finally, we'll use the word <quote>bisect</quote>, as both a 20.876 + noun and a verb, to stand in for the phrase <quote>search using 20.877 + the <command role="hg-cmd">hg bisect</command> 20.878 + command</quote>.</para> 20.879 + 20.880 + <para id="x_12f">One simple way to automate the searching process would be 20.881 + simply to probe every changeset. However, this scales poorly. 20.882 + If it took ten minutes to test a single changeset, and you had 20.883 + 10,000 changesets in your repository, the exhaustive approach 20.884 + would take on average 35 <emphasis>days</emphasis> to find the 20.885 + changeset that introduced a bug. Even if you knew that the bug 20.886 + was introduced by one of the last 500 changesets, and limited 20.887 + your search to those, you'd still be looking at over 40 hours to 20.888 + find the changeset that introduced your bug.</para> 20.889 + 20.890 + <para id="x_130">What the <command role="hg-cmd">hg bisect</command> command 20.891 + does is use its knowledge of the <quote>shape</quote> of your 20.892 + project's revision history to perform a search in time 20.893 + proportional to the <emphasis>logarithm</emphasis> of the number 20.894 + of changesets to check (the kind of search it performs is called 20.895 + a dichotomic search). With this approach, searching through 20.896 + 10,000 changesets will take less than three hours, even at ten 20.897 + minutes per test (the search will require about 14 tests). 20.898 + Limit your search to the last hundred changesets, and it will 20.899 + take only about an hour (roughly seven tests).</para> 20.900 + 20.901 + <para id="x_131">The <command role="hg-cmd">hg bisect</command> command is 20.902 + aware of the <quote>branchy</quote> nature of a Mercurial 20.903 + project's revision history, so it has no problems dealing with 20.904 + branches, merges, or multiple heads in a repository. It can 20.905 + prune entire branches of history with a single probe, which is 20.906 + how it operates so efficiently.</para> 20.907 + 20.908 + <sect2> 20.909 + <title>Using the <command role="hg-cmd">hg bisect</command> 20.910 + command</title> 20.911 + 20.912 + <para id="x_132">Here's an example of <command role="hg-cmd">hg 20.913 + bisect</command> in action.</para> 20.914 + 20.915 + <note> 20.916 + <para id="x_133"> In versions 0.9.5 and earlier of Mercurial, <command 20.917 + role="hg-cmd">hg bisect</command> was not a core command: 20.918 + it was distributed with Mercurial as an extension. This 20.919 + section describes the built-in command, not the old 20.920 + extension.</para> 20.921 + </note> 20.922 + 20.923 + <para id="x_134">Now let's create a repository, so that we can try out the 20.924 + <command role="hg-cmd">hg bisect</command> command in 20.925 + isolation.</para> 20.926 + 20.927 + &interaction.bisect.init; 20.928 + 20.929 + <para id="x_135">We'll simulate a project that has a bug in it in a 20.930 + simple-minded way: create trivial changes in a loop, and 20.931 + nominate one specific change that will have the 20.932 + <quote>bug</quote>. This loop creates 35 changesets, each 20.933 + adding a single file to the repository. We'll represent our 20.934 + <quote>bug</quote> with a file that contains the text <quote>i 20.935 + have a gub</quote>.</para> 20.936 + 20.937 + &interaction.bisect.commits; 20.938 + 20.939 + <para id="x_136">The next thing that we'd like to do is figure out how to 20.940 + use the <command role="hg-cmd">hg bisect</command> command. 20.941 + We can use Mercurial's normal built-in help mechanism for 20.942 + this.</para> 20.943 + 20.944 + &interaction.bisect.help; 20.945 + 20.946 + <para id="x_137">The <command role="hg-cmd">hg bisect</command> command 20.947 + works in steps. Each step proceeds as follows.</para> 20.948 + <orderedlist> 20.949 + <listitem><para id="x_138">You run your binary test.</para> 20.950 + <itemizedlist> 20.951 + <listitem><para id="x_139">If the test succeeded, you tell <command 20.952 + role="hg-cmd">hg bisect</command> by running the 20.953 + <command role="hg-cmd">hg bisect --good</command> 20.954 + command.</para> 20.955 + </listitem> 20.956 + <listitem><para id="x_13a">If it failed, run the <command 20.957 + role="hg-cmd">hg bisect --bad</command> 20.958 + command.</para></listitem></itemizedlist> 20.959 + </listitem> 20.960 + <listitem><para id="x_13b">The command uses your information to decide 20.961 + which changeset to test next.</para> 20.962 + </listitem> 20.963 + <listitem><para id="x_13c">It updates the working directory to that 20.964 + changeset, and the process begins again.</para> 20.965 + </listitem></orderedlist> 20.966 + <para id="x_13d">The process ends when <command role="hg-cmd">hg 20.967 + bisect</command> identifies a unique changeset that marks 20.968 + the point where your test transitioned from 20.969 + <quote>succeeding</quote> to <quote>failing</quote>.</para> 20.970 + 20.971 + <para id="x_13e">To start the search, we must run the <command 20.972 + role="hg-cmd">hg bisect --reset</command> command.</para> 20.973 + 20.974 + &interaction.bisect.search.init; 20.975 + 20.976 + <para id="x_13f">In our case, the binary test we use is simple: we check to 20.977 + see if any file in the repository contains the string <quote>i 20.978 + have a gub</quote>. If it does, this changeset contains the 20.979 + change that <quote>caused the bug</quote>. By convention, a 20.980 + changeset that has the property we're searching for is 20.981 + <quote>bad</quote>, while one that doesn't is 20.982 + <quote>good</quote>.</para> 20.983 + 20.984 + <para id="x_140">Most of the time, the revision to which the working 20.985 + directory is synced (usually the tip) already exhibits the 20.986 + problem introduced by the buggy change, so we'll mark it as 20.987 + <quote>bad</quote>.</para> 20.988 + 20.989 + &interaction.bisect.search.bad-init; 20.990 + 20.991 + <para id="x_141">Our next task is to nominate a changeset that we know 20.992 + <emphasis>doesn't</emphasis> have the bug; the <command 20.993 + role="hg-cmd">hg bisect</command> command will 20.994 + <quote>bracket</quote> its search between the first pair of 20.995 + good and bad changesets. In our case, we know that revision 20.996 + 10 didn't have the bug. (I'll have more words about choosing 20.997 + the first <quote>good</quote> changeset later.)</para> 20.998 + 20.999 + &interaction.bisect.search.good-init; 20.1000 + 20.1001 + <para id="x_142">Notice that this command printed some output.</para> 20.1002 + <itemizedlist> 20.1003 + <listitem><para id="x_143">It told us how many changesets it must 20.1004 + consider before it can identify the one that introduced 20.1005 + the bug, and how many tests that will require.</para> 20.1006 + </listitem> 20.1007 + <listitem><para id="x_144">It updated the working directory to the next 20.1008 + changeset to test, and told us which changeset it's 20.1009 + testing.</para> 20.1010 + </listitem></itemizedlist> 20.1011 + 20.1012 + <para id="x_145">We now run our test in the working directory. We use the 20.1013 + <command>grep</command> command to see if our 20.1014 + <quote>bad</quote> file is present in the working directory. 20.1015 + If it is, this revision is bad; if not, this revision is good. 20.1016 + &interaction.bisect.search.step1;</para> 20.1017 + 20.1018 + <para id="x_146">This test looks like a perfect candidate for automation, 20.1019 + so let's turn it into a shell function.</para> 20.1020 + &interaction.bisect.search.mytest; 20.1021 + 20.1022 + <para id="x_147">We can now run an entire test step with a single command, 20.1023 + <literal>mytest</literal>.</para> 20.1024 + 20.1025 + &interaction.bisect.search.step2; 20.1026 + 20.1027 + <para id="x_148">A few more invocations of our canned test step command, 20.1028 + and we're done.</para> 20.1029 + 20.1030 + &interaction.bisect.search.rest; 20.1031 + 20.1032 + <para id="x_149">Even though we had 40 changesets to search through, the 20.1033 + <command role="hg-cmd">hg bisect</command> command let us find 20.1034 + the changeset that introduced our <quote>bug</quote> with only 20.1035 + five tests. Because the number of tests that the <command 20.1036 + role="hg-cmd">hg bisect</command> command performs grows 20.1037 + logarithmically with the number of changesets to search, the 20.1038 + advantage that it has over the <quote>brute force</quote> 20.1039 + search approach increases with every changeset you add.</para> 20.1040 + 20.1041 + </sect2> 20.1042 + <sect2> 20.1043 + <title>Cleaning up after your search</title> 20.1044 + 20.1045 + <para id="x_14a">When you're finished using the <command role="hg-cmd">hg 20.1046 + bisect</command> command in a repository, you can use the 20.1047 + <command role="hg-cmd">hg bisect --reset</command> command to 20.1048 + drop the information it was using to drive your search. The 20.1049 + command doesn't use much space, so it doesn't matter if you 20.1050 + forget to run this command. However, <command 20.1051 + role="hg-cmd">hg bisect</command> won't let you start a new 20.1052 + search in that repository until you do a <command 20.1053 + role="hg-cmd">hg bisect --reset</command>.</para> 20.1054 + 20.1055 + &interaction.bisect.search.reset; 20.1056 + 20.1057 + </sect2> 20.1058 + </sect1> 20.1059 + <sect1> 20.1060 + <title>Tips for finding bugs effectively</title> 20.1061 + 20.1062 + <sect2> 20.1063 + <title>Give consistent input</title> 20.1064 + 20.1065 + <para id="x_14b">The <command role="hg-cmd">hg bisect</command> command 20.1066 + requires that you correctly report the result of every test 20.1067 + you perform. If you tell it that a test failed when it really 20.1068 + succeeded, it <emphasis>might</emphasis> be able to detect the 20.1069 + inconsistency. If it can identify an inconsistency in your 20.1070 + reports, it will tell you that a particular changeset is both 20.1071 + good and bad. However, it can't do this perfectly; it's about 20.1072 + as likely to report the wrong changeset as the source of the 20.1073 + bug.</para> 20.1074 + 20.1075 + </sect2> 20.1076 + <sect2> 20.1077 + <title>Automate as much as possible</title> 20.1078 + 20.1079 + <para id="x_14c">When I started using the <command role="hg-cmd">hg 20.1080 + bisect</command> command, I tried a few times to run my 20.1081 + tests by hand, on the command line. This is an approach that 20.1082 + I, at least, am not suited to. After a few tries, I found 20.1083 + that I was making enough mistakes that I was having to restart 20.1084 + my searches several times before finally getting correct 20.1085 + results.</para> 20.1086 + 20.1087 + <para id="x_14d">My initial problems with driving the <command 20.1088 + role="hg-cmd">hg bisect</command> command by hand occurred 20.1089 + even with simple searches on small repositories; if the 20.1090 + problem you're looking for is more subtle, or the number of 20.1091 + tests that <command role="hg-cmd">hg bisect</command> must 20.1092 + perform increases, the likelihood of operator error ruining 20.1093 + the search is much higher. Once I started automating my 20.1094 + tests, I had much better results.</para> 20.1095 + 20.1096 + <para id="x_14e">The key to automated testing is twofold:</para> 20.1097 + <itemizedlist> 20.1098 + <listitem><para id="x_14f">always test for the same symptom, and</para> 20.1099 + </listitem> 20.1100 + <listitem><para id="x_150">always feed consistent input to the <command 20.1101 + role="hg-cmd">hg bisect</command> command.</para> 20.1102 + </listitem></itemizedlist> 20.1103 + <para id="x_151">In my tutorial example above, the <command>grep</command> 20.1104 + command tests for the symptom, and the <literal>if</literal> 20.1105 + statement takes the result of this check and ensures that we 20.1106 + always feed the same input to the <command role="hg-cmd">hg 20.1107 + bisect</command> command. The <literal>mytest</literal> 20.1108 + function marries these together in a reproducible way, so that 20.1109 + every test is uniform and consistent.</para> 20.1110 + 20.1111 + </sect2> 20.1112 + <sect2> 20.1113 + <title>Check your results</title> 20.1114 + 20.1115 + <para id="x_152">Because the output of a <command role="hg-cmd">hg 20.1116 + bisect</command> search is only as good as the input you 20.1117 + give it, don't take the changeset it reports as the absolute 20.1118 + truth. A simple way to cross-check its report is to manually 20.1119 + run your test at each of the following changesets:</para> 20.1120 + <itemizedlist> 20.1121 + <listitem><para id="x_153">The changeset that it reports as the first bad 20.1122 + revision. Your test should still report this as 20.1123 + bad.</para> 20.1124 + </listitem> 20.1125 + <listitem><para id="x_154">The parent of that changeset (either parent, 20.1126 + if it's a merge). Your test should report this changeset 20.1127 + as good.</para> 20.1128 + </listitem> 20.1129 + <listitem><para id="x_155">A child of that changeset. Your test should 20.1130 + report this changeset as bad.</para> 20.1131 + </listitem></itemizedlist> 20.1132 + 20.1133 + </sect2> 20.1134 + <sect2> 20.1135 + <title>Beware interference between bugs</title> 20.1136 + 20.1137 + <para id="x_156">It's possible that your search for one bug could be 20.1138 + disrupted by the presence of another. For example, let's say 20.1139 + your software crashes at revision 100, and worked correctly at 20.1140 + revision 50. Unknown to you, someone else introduced a 20.1141 + different crashing bug at revision 60, and fixed it at 20.1142 + revision 80. This could distort your results in one of 20.1143 + several ways.</para> 20.1144 + 20.1145 + <para id="x_157">It is possible that this other bug completely 20.1146 + <quote>masks</quote> yours, which is to say that it occurs 20.1147 + before your bug has a chance to manifest itself. If you can't 20.1148 + avoid that other bug (for example, it prevents your project 20.1149 + from building), and so can't tell whether your bug is present 20.1150 + in a particular changeset, the <command role="hg-cmd">hg 20.1151 + bisect</command> command cannot help you directly. Instead, 20.1152 + you can mark a changeset as untested by running <command 20.1153 + role="hg-cmd">hg bisect --skip</command>.</para> 20.1154 + 20.1155 + <para id="x_158">A different problem could arise if your test for a bug's 20.1156 + presence is not specific enough. If you check for <quote>my 20.1157 + program crashes</quote>, then both your crashing bug and an 20.1158 + unrelated crashing bug that masks it will look like the same 20.1159 + thing, and mislead <command role="hg-cmd">hg 20.1160 + bisect</command>.</para> 20.1161 + 20.1162 + <para id="x_159">Another useful situation in which to use <command 20.1163 + role="hg-cmd">hg bisect --skip</command> is if you can't 20.1164 + test a revision because your project was in a broken and hence 20.1165 + untestable state at that revision, perhaps because someone 20.1166 + checked in a change that prevented the project from 20.1167 + building.</para> 20.1168 + 20.1169 + </sect2> 20.1170 + <sect2> 20.1171 + <title>Bracket your search lazily</title> 20.1172 + 20.1173 + <para id="x_15a">Choosing the first <quote>good</quote> and 20.1174 + <quote>bad</quote> changesets that will mark the end points of 20.1175 + your search is often easy, but it bears a little discussion 20.1176 + nevertheless. From the perspective of <command 20.1177 + role="hg-cmd">hg bisect</command>, the <quote>newest</quote> 20.1178 + changeset is conventionally <quote>bad</quote>, and the older 20.1179 + changeset is <quote>good</quote>.</para> 20.1180 + 20.1181 + <para id="x_15b">If you're having trouble remembering when a suitable 20.1182 + <quote>good</quote> change was, so that you can tell <command 20.1183 + role="hg-cmd">hg bisect</command>, you could do worse than 20.1184 + testing changesets at random. Just remember to eliminate 20.1185 + contenders that can't possibly exhibit the bug (perhaps 20.1186 + because the feature with the bug isn't present yet) and those 20.1187 + where another problem masks the bug (as I discussed 20.1188 + above).</para> 20.1189 + 20.1190 + <para id="x_15c">Even if you end up <quote>early</quote> by thousands of 20.1191 + changesets or months of history, you will only add a handful 20.1192 + of tests to the total number that <command role="hg-cmd">hg 20.1193 + bisect</command> must perform, thanks to its logarithmic 20.1194 + behavior.</para> 20.1195 + 20.1196 + </sect2> 20.1197 + </sect1> 20.1198 +</chapter> 20.1199 + 20.1200 +<!-- 20.1201 +local variables: 20.1202 +sgml-parent-document: ("00book.xml" "book" "chapter") 20.1203 +end: 20.1204 +-->
21.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 21.2 +++ b/en/ch10-hook.xml Thu May 07 21:07:35 2009 -0700 21.3 @@ -0,0 +1,1928 @@ 21.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 21.5 + 21.6 +<chapter id="chap:hook"> 21.7 + <?dbhtml filename="handling-repository-events-with-hooks.html"?> 21.8 + <title>Handling repository events with hooks</title> 21.9 + 21.10 + <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform 21.11 + automated actions in response to events that occur in a 21.12 + repository. In some cases, you can even control Mercurial's 21.13 + response to those events.</para> 21.14 + 21.15 + <para id="x_1e7">The name Mercurial uses for one of these actions is a 21.16 + <emphasis>hook</emphasis>. Hooks are called 21.17 + <quote>triggers</quote> in some revision control systems, but the 21.18 + two names refer to the same idea.</para> 21.19 + 21.20 + <sect1> 21.21 + <title>An overview of hooks in Mercurial</title> 21.22 + 21.23 + <para id="x_1e8">Here is a brief list of the hooks that Mercurial 21.24 + supports. We will revisit each of these hooks in more detail 21.25 + later, in <xref linkend="sec:hook:ref"/>.</para> 21.26 + 21.27 + <para id="x_1f6">Each of the hooks whose description begins with the word 21.28 + <quote>Controlling</quote> has the ability to determine whether 21.29 + an activity can proceed. If the hook succeeds, the activity may 21.30 + proceed; if it fails, the activity is either not permitted or 21.31 + undone, depending on the hook.</para> 21.32 + 21.33 + <itemizedlist> 21.34 + <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This 21.35 + is run after a group of changesets has been brought into the 21.36 + repository from elsewhere.</para> 21.37 + </listitem> 21.38 + <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is 21.39 + run after a new changeset has been created in the local 21.40 + repository.</para> 21.41 + </listitem> 21.42 + <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is 21.43 + run once for each new changeset that is brought into the 21.44 + repository from elsewhere. Notice the difference from 21.45 + <literal role="hook">changegroup</literal>, which is run 21.46 + once per <emphasis>group</emphasis> of changesets brought 21.47 + in.</para> 21.48 + </listitem> 21.49 + <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is 21.50 + run after a group of changesets has been transmitted from 21.51 + this repository.</para> 21.52 + </listitem> 21.53 + <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>: 21.54 + This is run before starting to bring a group of changesets 21.55 + into the repository. 21.56 + </para> 21.57 + </listitem> 21.58 + <listitem><para id="x_1ee"><literal role="hook">precommit</literal>: 21.59 + Controlling. This is run before starting a commit. 21.60 + </para> 21.61 + </listitem> 21.62 + <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>: 21.63 + Controlling. This is run before starting to transmit a group 21.64 + of changesets from this repository. 21.65 + </para> 21.66 + </listitem> 21.67 + <listitem><para id="x_1f0"><literal role="hook">pretag</literal>: 21.68 + Controlling. This is run before creating a tag. 21.69 + </para> 21.70 + </listitem> 21.71 + <listitem><para id="x_1f1"><literal 21.72 + role="hook">pretxnchangegroup</literal>: Controlling. This 21.73 + is run after a group of changesets has been brought into the 21.74 + local repository from another, but before the transaction 21.75 + completes that will make the changes permanent in the 21.76 + repository. 21.77 + </para> 21.78 + </listitem> 21.79 + <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>: 21.80 + Controlling. This is run after a new changeset has been 21.81 + created in the local repository, but before the transaction 21.82 + completes that will make it permanent. 21.83 + </para> 21.84 + </listitem> 21.85 + <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>: 21.86 + Controlling. This is run before starting an update or merge 21.87 + of the working directory. 21.88 + </para> 21.89 + </listitem> 21.90 + <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run 21.91 + after a tag is created. 21.92 + </para> 21.93 + </listitem> 21.94 + <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is 21.95 + run after an update or merge of the working directory has 21.96 + finished. 21.97 + </para> 21.98 + </listitem></itemizedlist> 21.99 + 21.100 + </sect1> 21.101 + <sect1> 21.102 + <title>Hooks and security</title> 21.103 + 21.104 + <sect2> 21.105 + <title>Hooks are run with your privileges</title> 21.106 + 21.107 + <para id="x_1f7">When you run a Mercurial command in a repository, and the 21.108 + command causes a hook to run, that hook runs on 21.109 + <emphasis>your</emphasis> system, under 21.110 + <emphasis>your</emphasis> user account, with 21.111 + <emphasis>your</emphasis> privilege level. Since hooks are 21.112 + arbitrary pieces of executable code, you should treat them 21.113 + with an appropriate level of suspicion. Do not install a hook 21.114 + unless you are confident that you know who created it and what 21.115 + it does. 21.116 + </para> 21.117 + 21.118 + <para id="x_1f8">In some cases, you may be exposed to hooks that you did 21.119 + not install yourself. If you work with Mercurial on an 21.120 + unfamiliar system, Mercurial will run hooks defined in that 21.121 + system's global <filename role="special">~/.hgrc</filename> 21.122 + file. 21.123 + </para> 21.124 + 21.125 + <para id="x_1f9">If you are working with a repository owned by another 21.126 + user, Mercurial can run hooks defined in that user's 21.127 + repository, but it will still run them as <quote>you</quote>. 21.128 + For example, if you <command role="hg-cmd">hg pull</command> 21.129 + from that repository, and its <filename 21.130 + role="special">.hg/hgrc</filename> defines a local <literal 21.131 + role="hook">outgoing</literal> hook, that hook will run 21.132 + under your user account, even though you don't own that 21.133 + repository. 21.134 + </para> 21.135 + 21.136 + <note> 21.137 + <para id="x_1fa"> This only applies if you are pulling from a repository 21.138 + on a local or network filesystem. If you're pulling over 21.139 + http or ssh, any <literal role="hook">outgoing</literal> 21.140 + hook will run under whatever account is executing the server 21.141 + process, on the server. 21.142 + </para> 21.143 + </note> 21.144 + 21.145 + <para id="x_1fb">To see what hooks are defined in a repository, 21.146 + use the <command role="hg-cmd">hg showconfig hooks</command> 21.147 + command. If you are working in one repository, but talking to 21.148 + another that you do not own (e.g. using <command 21.149 + role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 21.150 + incoming</command>), remember that it is the other 21.151 + repository's hooks you should be checking, not your own. 21.152 + </para> 21.153 + </sect2> 21.154 + 21.155 + <sect2> 21.156 + <title>Hooks do not propagate</title> 21.157 + 21.158 + <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do 21.159 + not propagate when you clone, or pull from, a repository. The 21.160 + reason for this is simple: a hook is a completely arbitrary 21.161 + piece of executable code. It runs under your user identity, 21.162 + with your privilege level, on your machine. 21.163 + </para> 21.164 + 21.165 + <para id="x_1fd">It would be extremely reckless for any distributed 21.166 + revision control system to implement revision-controlled 21.167 + hooks, as this would offer an easily exploitable way to 21.168 + subvert the accounts of users of the revision control system. 21.169 + </para> 21.170 + 21.171 + <para id="x_1fe">Since Mercurial does not propagate hooks, if you are 21.172 + collaborating with other people on a common project, you 21.173 + should not assume that they are using the same Mercurial hooks 21.174 + as you are, or that theirs are correctly configured. You 21.175 + should document the hooks you expect people to use. 21.176 + </para> 21.177 + 21.178 + <para id="x_1ff">In a corporate intranet, this is somewhat easier to 21.179 + control, as you can for example provide a 21.180 + <quote>standard</quote> installation of Mercurial on an NFS 21.181 + filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will 21.182 + see. However, this too has its limits; see below. 21.183 + </para> 21.184 + </sect2> 21.185 + 21.186 + <sect2> 21.187 + <title>Hooks can be overridden</title> 21.188 + 21.189 + <para id="x_200">Mercurial allows you to override a hook definition by 21.190 + redefining the hook. You can disable it by setting its value 21.191 + to the empty string, or change its behavior as you wish. 21.192 + </para> 21.193 + 21.194 + <para id="x_201">If you deploy a system- or site-wide <filename 21.195 + role="special">~/.hgrc</filename> file that defines some 21.196 + hooks, you should thus understand that your users can disable 21.197 + or override those hooks. 21.198 + </para> 21.199 + </sect2> 21.200 + 21.201 + <sect2> 21.202 + <title>Ensuring that critical hooks are run</title> 21.203 + 21.204 + <para id="x_202">Sometimes you may want to enforce a policy that you do not 21.205 + want others to be able to work around. For example, you may 21.206 + have a requirement that every changeset must pass a rigorous 21.207 + set of tests. Defining this requirement via a hook in a 21.208 + site-wide <filename role="special">~/.hgrc</filename> won't 21.209 + work for remote users on laptops, and of course local users 21.210 + can subvert it at will by overriding the hook. 21.211 + </para> 21.212 + 21.213 + <para id="x_203">Instead, you can set up your policies for use of Mercurial 21.214 + so that people are expected to propagate changes through a 21.215 + well-known <quote>canonical</quote> server that you have 21.216 + locked down and configured appropriately. 21.217 + </para> 21.218 + 21.219 + <para id="x_204">One way to do this is via a combination of social 21.220 + engineering and technology. Set up a restricted-access 21.221 + account; users can push changes over the network to 21.222 + repositories managed by this account, but they cannot log into 21.223 + the account and run normal shell commands. In this scenario, 21.224 + a user can commit a changeset that contains any old garbage 21.225 + they want. 21.226 + </para> 21.227 + 21.228 + <para id="x_205">When someone pushes a changeset to the server that 21.229 + everyone pulls from, the server will test the changeset before 21.230 + it accepts it as permanent, and reject it if it fails to pass 21.231 + the test suite. If people only pull changes from this 21.232 + filtering server, it will serve to ensure that all changes 21.233 + that people pull have been automatically vetted. 21.234 + </para> 21.235 + 21.236 + </sect2> 21.237 + </sect1> 21.238 + 21.239 + <sect1 id="sec:hook:simple"> 21.240 + <title>A short tutorial on using hooks</title> 21.241 + 21.242 + <para id="x_212">It is easy to write a Mercurial hook. Let's start with a 21.243 + hook that runs when you finish a <command role="hg-cmd">hg 21.244 + commit</command>, and simply prints the hash of the changeset 21.245 + you just created. The hook is called <literal 21.246 + role="hook">commit</literal>. 21.247 + </para> 21.248 + 21.249 + <para id="x_213">All hooks follow the pattern in this example.</para> 21.250 + 21.251 +&interaction.hook.simple.init; 21.252 + 21.253 + <para id="x_214">You add an entry to the <literal 21.254 + role="rc-hooks">hooks</literal> section of your <filename 21.255 + role="special">~/.hgrc</filename>. On the left is the name of 21.256 + the event to trigger on; on the right is the action to take. As 21.257 + you can see, you can run an arbitrary shell command in a hook. 21.258 + Mercurial passes extra information to the hook using environment 21.259 + variables (look for <envar>HG_NODE</envar> in the example). 21.260 + </para> 21.261 + 21.262 + <sect2> 21.263 + <title>Performing multiple actions per event</title> 21.264 + 21.265 + <para id="x_215">Quite often, you will want to define more than one hook 21.266 + for a particular kind of event, as shown below.</para> 21.267 + 21.268 +&interaction.hook.simple.ext; 21.269 + 21.270 + <para id="x_216">Mercurial lets you do this by adding an 21.271 + <emphasis>extension</emphasis> to the end of a hook's name. 21.272 + You extend a hook's name by giving the name of the hook, 21.273 + followed by a full stop (the 21.274 + <quote><literal>.</literal></quote> character), followed by 21.275 + some more text of your choosing. For example, Mercurial will 21.276 + run both <literal>commit.foo</literal> and 21.277 + <literal>commit.bar</literal> when the 21.278 + <literal>commit</literal> event occurs. 21.279 + </para> 21.280 + 21.281 + <para id="x_217">To give a well-defined order of execution when there are 21.282 + multiple hooks defined for an event, Mercurial sorts hooks by 21.283 + extension, and executes the hook commands in this sorted 21.284 + order. In the above example, it will execute 21.285 + <literal>commit.bar</literal> before 21.286 + <literal>commit.foo</literal>, and <literal>commit</literal> 21.287 + before both. 21.288 + </para> 21.289 + 21.290 + <para id="x_218">It is a good idea to use a somewhat descriptive 21.291 + extension when you define a new hook. This will help you to 21.292 + remember what the hook was for. If the hook fails, you'll get 21.293 + an error message that contains the hook name and extension, so 21.294 + using a descriptive extension could give you an immediate hint 21.295 + as to why the hook failed (see <xref 21.296 + linkend="sec:hook:perm"/> for an example). 21.297 + </para> 21.298 + 21.299 + </sect2> 21.300 + <sect2 id="sec:hook:perm"> 21.301 + <title>Controlling whether an activity can proceed</title> 21.302 + 21.303 + <para id="x_219">In our earlier examples, we used the <literal 21.304 + role="hook">commit</literal> hook, which is run after a 21.305 + commit has completed. This is one of several Mercurial hooks 21.306 + that run after an activity finishes. Such hooks have no way 21.307 + of influencing the activity itself. 21.308 + </para> 21.309 + 21.310 + <para id="x_21a">Mercurial defines a number of events that occur before an 21.311 + activity starts; or after it starts, but before it finishes. 21.312 + Hooks that trigger on these events have the added ability to 21.313 + choose whether the activity can continue, or will abort. 21.314 + </para> 21.315 + 21.316 + <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs 21.317 + after a commit has all but completed. In other words, the 21.318 + metadata representing the changeset has been written out to 21.319 + disk, but the transaction has not yet been allowed to 21.320 + complete. The <literal role="hook">pretxncommit</literal> 21.321 + hook has the ability to decide whether the transaction can 21.322 + complete, or must be rolled back. 21.323 + </para> 21.324 + 21.325 + <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook 21.326 + exits with a status code of zero, the transaction is allowed 21.327 + to complete; the commit finishes; and the <literal 21.328 + role="hook">commit</literal> hook is run. If the <literal 21.329 + role="hook">pretxncommit</literal> hook exits with a 21.330 + non-zero status code, the transaction is rolled back; the 21.331 + metadata representing the changeset is erased; and the 21.332 + <literal role="hook">commit</literal> hook is not run. 21.333 + </para> 21.334 + 21.335 +&interaction.hook.simple.pretxncommit; 21.336 + 21.337 + <para id="x_21d">The hook in the example above checks that a commit comment 21.338 + contains a bug ID. If it does, the commit can complete. If 21.339 + not, the commit is rolled back. 21.340 + </para> 21.341 + 21.342 + </sect2> 21.343 + </sect1> 21.344 + <sect1> 21.345 + <title>Writing your own hooks</title> 21.346 + 21.347 + <para id="x_21e">When you are writing a hook, you might find it useful to run 21.348 + Mercurial either with the <option 21.349 + role="hg-opt-global">-v</option> option, or the <envar 21.350 + role="rc-item-ui">verbose</envar> config item set to 21.351 + <quote>true</quote>. When you do so, Mercurial will print a 21.352 + message before it calls each hook. 21.353 + </para> 21.354 + 21.355 + <sect2 id="sec:hook:lang"> 21.356 + <title>Choosing how your hook should run</title> 21.357 + 21.358 + <para id="x_21f">You can write a hook either as a normal 21.359 + program&emdash;typically a shell script&emdash;or as a Python 21.360 + function that is executed within the Mercurial process. 21.361 + </para> 21.362 + 21.363 + <para id="x_220">Writing a hook as an external program has the advantage 21.364 + that it requires no knowledge of Mercurial's internals. You 21.365 + can call normal Mercurial commands to get any added 21.366 + information you need. The trade-off is that external hooks 21.367 + are slower than in-process hooks. 21.368 + </para> 21.369 + 21.370 + <para id="x_221">An in-process Python hook has complete access to the 21.371 + Mercurial API, and does not <quote>shell out</quote> to 21.372 + another process, so it is inherently faster than an external 21.373 + hook. It is also easier to obtain much of the information 21.374 + that a hook requires by using the Mercurial API than by 21.375 + running Mercurial commands. 21.376 + </para> 21.377 + 21.378 + <para id="x_222">If you are comfortable with Python, or require high 21.379 + performance, writing your hooks in Python may be a good 21.380 + choice. However, when you have a straightforward hook to 21.381 + write and you don't need to care about performance (probably 21.382 + the majority of hooks), a shell script is perfectly fine. 21.383 + </para> 21.384 + 21.385 + </sect2> 21.386 + <sect2 id="sec:hook:param"> 21.387 + <title>Hook parameters</title> 21.388 + 21.389 + <para id="x_223">Mercurial calls each hook with a set of well-defined 21.390 + parameters. In Python, a parameter is passed as a keyword 21.391 + argument to your hook function. For an external program, a 21.392 + parameter is passed as an environment variable. 21.393 + </para> 21.394 + 21.395 + <para id="x_224">Whether your hook is written in Python or as a shell 21.396 + script, the hook-specific parameter names and values will be 21.397 + the same. A boolean parameter will be represented as a 21.398 + boolean value in Python, but as the number 1 (for 21.399 + <quote>true</quote>) or 0 (for <quote>false</quote>) as an 21.400 + environment variable for an external hook. If a hook 21.401 + parameter is named <literal>foo</literal>, the keyword 21.402 + argument for a Python hook will also be named 21.403 + <literal>foo</literal>, while the environment variable for an 21.404 + external hook will be named <literal>HG_FOO</literal>. 21.405 + </para> 21.406 + </sect2> 21.407 + 21.408 + <sect2> 21.409 + <title>Hook return values and activity control</title> 21.410 + 21.411 + <para id="x_225">A hook that executes successfully must exit with a status 21.412 + of zero if external, or return boolean <quote>false</quote> if 21.413 + in-process. Failure is indicated with a non-zero exit status 21.414 + from an external hook, or an in-process hook returning boolean 21.415 + <quote>true</quote>. If an in-process hook raises an 21.416 + exception, the hook is considered to have failed. 21.417 + </para> 21.418 + 21.419 + <para id="x_226">For a hook that controls whether an activity can proceed, 21.420 + zero/false means <quote>allow</quote>, while 21.421 + non-zero/true/exception means <quote>deny</quote>. 21.422 + </para> 21.423 + </sect2> 21.424 + 21.425 + <sect2> 21.426 + <title>Writing an external hook</title> 21.427 + 21.428 + <para id="x_227">When you define an external hook in your <filename 21.429 + role="special">~/.hgrc</filename> and the hook is run, its 21.430 + value is passed to your shell, which interprets it. This 21.431 + means that you can use normal shell constructs in the body of 21.432 + the hook. 21.433 + </para> 21.434 + 21.435 + <para id="x_228">An executable hook is always run with its current 21.436 + directory set to a repository's root directory. 21.437 + </para> 21.438 + 21.439 + <para id="x_229">Each hook parameter is passed in as an environment 21.440 + variable; the name is upper-cased, and prefixed with the 21.441 + string <quote><literal>HG_</literal></quote>. 21.442 + </para> 21.443 + 21.444 + <para id="x_22a">With the exception of hook parameters, Mercurial does not 21.445 + set or modify any environment variables when running a hook. 21.446 + This is useful to remember if you are writing a site-wide hook 21.447 + that may be run by a number of different users with differing 21.448 + environment variables set. In multi-user situations, you 21.449 + should not rely on environment variables being set to the 21.450 + values you have in your environment when testing the hook. 21.451 + </para> 21.452 + </sect2> 21.453 + 21.454 + <sect2> 21.455 + <title>Telling Mercurial to use an in-process hook</title> 21.456 + 21.457 + <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax 21.458 + for defining an in-process hook is slightly different than for 21.459 + an executable hook. The value of the hook must start with the 21.460 + text <quote><literal>python:</literal></quote>, and continue 21.461 + with the fully-qualified name of a callable object to use as 21.462 + the hook's value. 21.463 + </para> 21.464 + 21.465 + <para id="x_22c">The module in which a hook lives is automatically imported 21.466 + when a hook is run. So long as you have the module name and 21.467 + <envar>PYTHONPATH</envar> right, it should <quote>just 21.468 + work</quote>. 21.469 + </para> 21.470 + 21.471 + <para id="x_22d">The following <filename role="special">~/.hgrc</filename> 21.472 + example snippet illustrates the syntax and meaning of the 21.473 + notions we just described. 21.474 + </para> 21.475 + <programlisting>[hooks] 21.476 +commit.example = python:mymodule.submodule.myhook</programlisting> 21.477 + <para id="x_22e">When Mercurial runs the <literal>commit.example</literal> 21.478 + hook, it imports <literal>mymodule.submodule</literal>, looks 21.479 + for the callable object named <literal>myhook</literal>, and 21.480 + calls it. 21.481 + </para> 21.482 + </sect2> 21.483 + 21.484 + <sect2> 21.485 + <title>Writing an in-process hook</title> 21.486 + 21.487 + <para id="x_22f">The simplest in-process hook does nothing, but illustrates 21.488 + the basic shape of the hook API: 21.489 + </para> 21.490 + <programlisting>def myhook(ui, repo, **kwargs): 21.491 + pass</programlisting> 21.492 + <para id="x_230">The first argument to a Python hook is always a <literal 21.493 + role="py-mod-mercurial.ui">ui</literal> object. The second 21.494 + is a repository object; at the moment, it is always an 21.495 + instance of <literal 21.496 + role="py-mod-mercurial.localrepo">localrepository</literal>. 21.497 + Following these two arguments are other keyword arguments. 21.498 + Which ones are passed in depends on the hook being called, but 21.499 + a hook can ignore arguments it doesn't care about by dropping 21.500 + them into a keyword argument dict, as with 21.501 + <literal>**kwargs</literal> above. 21.502 + </para> 21.503 + 21.504 + </sect2> 21.505 + </sect1> 21.506 + <sect1> 21.507 + <title>Some hook examples</title> 21.508 + 21.509 + <sect2> 21.510 + <title>Writing meaningful commit messages</title> 21.511 + 21.512 + <para id="x_231">It's hard to imagine a useful commit message being very 21.513 + short. The simple <literal role="hook">pretxncommit</literal> 21.514 + hook of the example below will prevent you from committing a 21.515 + changeset with a message that is less than ten bytes long. 21.516 + </para> 21.517 + 21.518 +&interaction.hook.msglen.go; 21.519 + </sect2> 21.520 + 21.521 + <sect2> 21.522 + <title>Checking for trailing whitespace</title> 21.523 + 21.524 + <para id="x_232">An interesting use of a commit-related hook is to help you 21.525 + to write cleaner code. A simple example of <quote>cleaner 21.526 + code</quote> is the dictum that a change should not add any 21.527 + new lines of text that contain <quote>trailing 21.528 + whitespace</quote>. Trailing whitespace is a series of 21.529 + space and tab characters at the end of a line of text. In 21.530 + most cases, trailing whitespace is unnecessary, invisible 21.531 + noise, but it is occasionally problematic, and people often 21.532 + prefer to get rid of it. 21.533 + </para> 21.534 + 21.535 + <para id="x_233">You can use either the <literal 21.536 + role="hook">precommit</literal> or <literal 21.537 + role="hook">pretxncommit</literal> hook to tell whether you 21.538 + have a trailing whitespace problem. If you use the <literal 21.539 + role="hook">precommit</literal> hook, the hook will not know 21.540 + which files you are committing, so it will have to check every 21.541 + modified file in the repository for trailing white space. If 21.542 + you want to commit a change to just the file 21.543 + <filename>foo</filename>, but the file 21.544 + <filename>bar</filename> contains trailing whitespace, doing a 21.545 + check in the <literal role="hook">precommit</literal> hook 21.546 + will prevent you from committing <filename>foo</filename> due 21.547 + to the problem with <filename>bar</filename>. This doesn't 21.548 + seem right. 21.549 + </para> 21.550 + 21.551 + <para id="x_234">Should you choose the <literal 21.552 + role="hook">pretxncommit</literal> hook, the check won't 21.553 + occur until just before the transaction for the commit 21.554 + completes. This will allow you to check for problems only the 21.555 + exact files that are being committed. However, if you entered 21.556 + the commit message interactively and the hook fails, the 21.557 + transaction will roll back; you'll have to re-enter the commit 21.558 + message after you fix the trailing whitespace and run <command 21.559 + role="hg-cmd">hg commit</command> again. 21.560 + </para> 21.561 + 21.562 + &interaction.ch09-hook.ws.simple; 21.563 + 21.564 + <para id="x_235">In this example, we introduce a simple <literal 21.565 + role="hook">pretxncommit</literal> hook that checks for 21.566 + trailing whitespace. This hook is short, but not very 21.567 + helpful. It exits with an error status if a change adds a 21.568 + line with trailing whitespace to any file, but does not print 21.569 + any information that might help us to identify the offending 21.570 + file or line. It also has the nice property of not paying 21.571 + attention to unmodified lines; only lines that introduce new 21.572 + trailing whitespace cause problems. 21.573 + </para> 21.574 + 21.575 + &ch09-check_whitespace.py.lst; 21.576 + 21.577 + <para id="x_236">The above version is much more complex, but also more 21.578 + useful. It parses a unified diff to see if any lines add 21.579 + trailing whitespace, and prints the name of the file and the 21.580 + line number of each such occurrence. Even better, if the 21.581 + change adds trailing whitespace, this hook saves the commit 21.582 + comment and prints the name of the save file before exiting 21.583 + and telling Mercurial to roll the transaction back, so you can 21.584 + use the <option role="hg-opt-commit">-l filename</option> 21.585 + option to <command role="hg-cmd">hg commit</command> to reuse 21.586 + the saved commit message once you've corrected the problem. 21.587 + </para> 21.588 + 21.589 + &interaction.ch09-hook.ws.better; 21.590 + 21.591 + <para id="x_237">As a final aside, note in the example above the 21.592 + use of <command>sed</command>'s in-place editing feature to 21.593 + get rid of trailing whitespace from a file. This is concise 21.594 + and useful enough that I will reproduce it here (using 21.595 + <command>perl</command> for good measure).</para> 21.596 + <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting> 21.597 + 21.598 + </sect2> 21.599 + </sect1> 21.600 + <sect1> 21.601 + <title>Bundled hooks</title> 21.602 + 21.603 + <para id="x_238">Mercurial ships with several bundled hooks. You can find 21.604 + them in the <filename class="directory">hgext</filename> 21.605 + directory of a Mercurial source tree. If you are using a 21.606 + Mercurial binary package, the hooks will be located in the 21.607 + <filename class="directory">hgext</filename> directory of 21.608 + wherever your package installer put Mercurial. 21.609 + </para> 21.610 + 21.611 + <sect2> 21.612 + <title><literal role="hg-ext">acl</literal>&emdash;access 21.613 + control for parts of a repository</title> 21.614 + 21.615 + <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets 21.616 + you control which remote users are allowed to push changesets 21.617 + to a networked server. You can protect any portion of a 21.618 + repository (including the entire repo), so that a specific 21.619 + remote user can push changes that do not affect the protected 21.620 + portion. 21.621 + </para> 21.622 + 21.623 + <para id="x_23a">This extension implements access control based on the 21.624 + identity of the user performing a push, 21.625 + <emphasis>not</emphasis> on who committed the changesets 21.626 + they're pushing. It makes sense to use this hook only if you 21.627 + have a locked-down server environment that authenticates 21.628 + remote users, and you want to be sure that only specific users 21.629 + are allowed to push changes to that server. 21.630 + </para> 21.631 + 21.632 + <sect3> 21.633 + <title>Configuring the <literal role="hook">acl</literal> 21.634 + hook</title> 21.635 + 21.636 + <para id="x_23b">In order to manage incoming changesets, the <literal 21.637 + role="hg-ext">acl</literal> hook must be used as a 21.638 + <literal role="hook">pretxnchangegroup</literal> hook. This 21.639 + lets it see which files are modified by each incoming 21.640 + changeset, and roll back a group of changesets if they 21.641 + modify <quote>forbidden</quote> files. Example: 21.642 + </para> 21.643 + <programlisting>[hooks] 21.644 +pretxnchangegroup.acl = python:hgext.acl.hook</programlisting> 21.645 + 21.646 + <para id="x_23c">The <literal role="hg-ext">acl</literal> extension is 21.647 + configured using three sections. 21.648 + </para> 21.649 + 21.650 + <para id="x_23d">The <literal role="rc-acl">acl</literal> section has 21.651 + only one entry, <envar role="rc-item-acl">sources</envar>, 21.652 + which lists the sources of incoming changesets that the hook 21.653 + should pay attention to. You don't normally need to 21.654 + configure this section. 21.655 + </para> 21.656 + <itemizedlist> 21.657 + <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>: 21.658 + Control incoming changesets that are arriving from a 21.659 + remote repository over http or ssh. This is the default 21.660 + value of <envar role="rc-item-acl">sources</envar>, and 21.661 + usually the only setting you'll need for this 21.662 + configuration item. 21.663 + </para> 21.664 + </listitem> 21.665 + <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>: 21.666 + Control incoming changesets that are arriving via a pull 21.667 + from a local repository. 21.668 + </para> 21.669 + </listitem> 21.670 + <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>: 21.671 + Control incoming changesets that are arriving via a push 21.672 + from a local repository. 21.673 + </para> 21.674 + </listitem> 21.675 + <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>: 21.676 + Control incoming changesets that are arriving from 21.677 + another repository via a bundle. 21.678 + </para> 21.679 + </listitem></itemizedlist> 21.680 + 21.681 + <para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal> 21.682 + section controls the users that are allowed to add 21.683 + changesets to the repository. If this section is not 21.684 + present, all users that are not explicitly denied are 21.685 + allowed. If this section is present, all users that are not 21.686 + explicitly allowed are denied (so an empty section means 21.687 + that all users are denied). 21.688 + </para> 21.689 + 21.690 + <para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal> 21.691 + section determines which users are denied from adding 21.692 + changesets to the repository. If this section is not 21.693 + present or is empty, no users are denied. 21.694 + </para> 21.695 + 21.696 + <para id="x_244">The syntaxes for the <literal 21.697 + role="rc-acl.allow">acl.allow</literal> and <literal 21.698 + role="rc-acl.deny">acl.deny</literal> sections are 21.699 + identical. On the left of each entry is a glob pattern that 21.700 + matches files or directories, relative to the root of the 21.701 + repository; on the right, a user name. 21.702 + </para> 21.703 + 21.704 + <para id="x_245">In the following example, the user 21.705 + <literal>docwriter</literal> can only push changes to the 21.706 + <filename class="directory">docs</filename> subtree of the 21.707 + repository, while <literal>intern</literal> can push changes 21.708 + to any file or directory except <filename 21.709 + class="directory">source/sensitive</filename>. 21.710 + </para> 21.711 + <programlisting>[acl.allow] 21.712 +docs/** = docwriter 21.713 +[acl.deny] 21.714 +source/sensitive/** = intern</programlisting> 21.715 + 21.716 + </sect3> 21.717 + <sect3> 21.718 + <title>Testing and troubleshooting</title> 21.719 + 21.720 + <para id="x_246">If you want to test the <literal 21.721 + role="hg-ext">acl</literal> hook, run it with Mercurial's 21.722 + debugging output enabled. Since you'll probably be running 21.723 + it on a server where it's not convenient (or sometimes 21.724 + possible) to pass in the <option 21.725 + role="hg-opt-global">--debug</option> option, don't forget 21.726 + that you can enable debugging output in your <filename 21.727 + role="special">~/.hgrc</filename>: 21.728 + </para> 21.729 + <programlisting>[ui] 21.730 +debug = true</programlisting> 21.731 + <para id="x_247">With this enabled, the <literal 21.732 + role="hg-ext">acl</literal> hook will print enough 21.733 + information to let you figure out why it is allowing or 21.734 + forbidding pushes from specific users. 21.735 + </para> 21.736 + 21.737 + </sect3> </sect2> 21.738 + 21.739 + <sect2> 21.740 + <title><literal 21.741 + role="hg-ext">bugzilla</literal>&emdash;integration with 21.742 + Bugzilla</title> 21.743 + 21.744 + <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension 21.745 + adds a comment to a Bugzilla bug whenever it finds a reference 21.746 + to that bug ID in a commit comment. You can install this hook 21.747 + on a shared server, so that any time a remote user pushes 21.748 + changes to this server, the hook gets run. 21.749 + </para> 21.750 + 21.751 + <para id="x_249">It adds a comment to the bug that looks like this (you can 21.752 + configure the contents of the comment&emdash;see below): 21.753 + </para> 21.754 + <programlisting>Changeset aad8b264143a, made by Joe User 21.755 + <joe.user@domain.com> in the frobnitz repository, refers 21.756 + to this bug. For complete details, see 21.757 + http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a 21.758 + Changeset description: Fix bug 10483 by guarding against some 21.759 + NULL pointers</programlisting> 21.760 + <para id="x_24a">The value of this hook is that it automates the process of 21.761 + updating a bug any time a changeset refers to it. If you 21.762 + configure the hook properly, it makes it easy for people to 21.763 + browse straight from a Bugzilla bug to a changeset that refers 21.764 + to that bug. 21.765 + </para> 21.766 + 21.767 + <para id="x_24b">You can use the code in this hook as a starting point for 21.768 + some more exotic Bugzilla integration recipes. Here are a few 21.769 + possibilities: 21.770 + </para> 21.771 + <itemizedlist> 21.772 + <listitem><para id="x_24c">Require that every changeset pushed to the 21.773 + server have a valid bug ID in its commit comment. In this 21.774 + case, you'd want to configure the hook as a <literal 21.775 + role="hook">pretxncommit</literal> hook. This would 21.776 + allow the hook to reject changes that didn't contain bug 21.777 + IDs. 21.778 + </para> 21.779 + </listitem> 21.780 + <listitem><para id="x_24d">Allow incoming changesets to automatically 21.781 + modify the <emphasis>state</emphasis> of a bug, as well as 21.782 + simply adding a comment. For example, the hook could 21.783 + recognise the string <quote>fixed bug 31337</quote> as 21.784 + indicating that it should update the state of bug 31337 to 21.785 + <quote>requires testing</quote>. 21.786 + </para> 21.787 + </listitem></itemizedlist> 21.788 + 21.789 + <sect3 id="sec:hook:bugzilla:config"> 21.790 + <title>Configuring the <literal role="hook">bugzilla</literal> 21.791 + hook</title> 21.792 + 21.793 + <para id="x_24e">You should configure this hook in your server's 21.794 + <filename role="special">~/.hgrc</filename> as an <literal 21.795 + role="hook">incoming</literal> hook, for example as 21.796 + follows: 21.797 + </para> 21.798 + <programlisting>[hooks] 21.799 +incoming.bugzilla = python:hgext.bugzilla.hook</programlisting> 21.800 + 21.801 + <para id="x_24f">Because of the specialised nature of this hook, and 21.802 + because Bugzilla was not written with this kind of 21.803 + integration in mind, configuring this hook is a somewhat 21.804 + involved process. 21.805 + </para> 21.806 + 21.807 + <para id="x_250">Before you begin, you must install the MySQL bindings 21.808 + for Python on the host(s) where you'll be running the hook. 21.809 + If this is not available as a binary package for your 21.810 + system, you can download it from 21.811 + <citation>web:mysql-python</citation>. 21.812 + </para> 21.813 + 21.814 + <para id="x_251">Configuration information for this hook lives in the 21.815 + <literal role="rc-bugzilla">bugzilla</literal> section of 21.816 + your <filename role="special">~/.hgrc</filename>. 21.817 + </para> 21.818 + <itemizedlist> 21.819 + <listitem><para id="x_252"><envar 21.820 + role="rc-item-bugzilla">version</envar>: The version 21.821 + of Bugzilla installed on the server. The database 21.822 + schema that Bugzilla uses changes occasionally, so this 21.823 + hook has to know exactly which schema to use.</para> 21.824 + </listitem> 21.825 + <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>: 21.826 + The hostname of the MySQL server that stores your 21.827 + Bugzilla data. The database must be configured to allow 21.828 + connections from whatever host you are running the 21.829 + <literal role="hook">bugzilla</literal> hook on. 21.830 + </para> 21.831 + </listitem> 21.832 + <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>: 21.833 + The username with which to connect to the MySQL server. 21.834 + The database must be configured to allow this user to 21.835 + connect from whatever host you are running the <literal 21.836 + role="hook">bugzilla</literal> hook on. This user 21.837 + must be able to access and modify Bugzilla tables. The 21.838 + default value of this item is <literal>bugs</literal>, 21.839 + which is the standard name of the Bugzilla user in a 21.840 + MySQL database. 21.841 + </para> 21.842 + </listitem> 21.843 + <listitem><para id="x_255"><envar 21.844 + role="rc-item-bugzilla">password</envar>: The MySQL 21.845 + password for the user you configured above. This is 21.846 + stored as plain text, so you should make sure that 21.847 + unauthorised users cannot read the <filename 21.848 + role="special">~/.hgrc</filename> file where you 21.849 + store this information. 21.850 + </para> 21.851 + </listitem> 21.852 + <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>: 21.853 + The name of the Bugzilla database on the MySQL server. 21.854 + The default value of this item is 21.855 + <literal>bugs</literal>, which is the standard name of 21.856 + the MySQL database where Bugzilla stores its data. 21.857 + </para> 21.858 + </listitem> 21.859 + <listitem><para id="x_257"><envar 21.860 + role="rc-item-bugzilla">notify</envar>: If you want 21.861 + Bugzilla to send out a notification email to subscribers 21.862 + after this hook has added a comment to a bug, you will 21.863 + need this hook to run a command whenever it updates the 21.864 + database. The command to run depends on where you have 21.865 + installed Bugzilla, but it will typically look something 21.866 + like this, if you have Bugzilla installed in <filename 21.867 + class="directory">/var/www/html/bugzilla</filename>: 21.868 + </para> 21.869 + <programlisting>cd /var/www/html/bugzilla && 21.870 + ./processmail %s nobody@nowhere.com</programlisting> 21.871 + </listitem> 21.872 + <listitem><para id="x_258"> The Bugzilla 21.873 + <literal>processmail</literal> program expects to be 21.874 + given a bug ID (the hook replaces 21.875 + <quote><literal>%s</literal></quote> with the bug ID) 21.876 + and an email address. It also expects to be able to 21.877 + write to some files in the directory that it runs in. 21.878 + If Bugzilla and this hook are not installed on the same 21.879 + machine, you will need to find a way to run 21.880 + <literal>processmail</literal> on the server where 21.881 + Bugzilla is installed. 21.882 + </para> 21.883 + </listitem></itemizedlist> 21.884 + 21.885 + </sect3> 21.886 + <sect3> 21.887 + <title>Mapping committer names to Bugzilla user names</title> 21.888 + 21.889 + <para id="x_259">By default, the <literal 21.890 + role="hg-ext">bugzilla</literal> hook tries to use the 21.891 + email address of a changeset's committer as the Bugzilla 21.892 + user name with which to update a bug. If this does not suit 21.893 + your needs, you can map committer email addresses to 21.894 + Bugzilla user names using a <literal 21.895 + role="rc-usermap">usermap</literal> section. 21.896 + </para> 21.897 + 21.898 + <para id="x_25a">Each item in the <literal 21.899 + role="rc-usermap">usermap</literal> section contains an 21.900 + email address on the left, and a Bugzilla user name on the 21.901 + right. 21.902 + </para> 21.903 + <programlisting>[usermap] 21.904 +jane.user@example.com = jane</programlisting> 21.905 + <para id="x_25b">You can either keep the <literal 21.906 + role="rc-usermap">usermap</literal> data in a normal 21.907 + <filename role="special">~/.hgrc</filename>, or tell the 21.908 + <literal role="hg-ext">bugzilla</literal> hook to read the 21.909 + information from an external <filename>usermap</filename> 21.910 + file. In the latter case, you can store 21.911 + <filename>usermap</filename> data by itself in (for example) 21.912 + a user-modifiable repository. This makes it possible to let 21.913 + your users maintain their own <envar 21.914 + role="rc-item-bugzilla">usermap</envar> entries. The main 21.915 + <filename role="special">~/.hgrc</filename> file might look 21.916 + like this: 21.917 + </para> 21.918 + <programlisting># regular hgrc file refers to external usermap file 21.919 +[bugzilla] 21.920 +usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> 21.921 + <para id="x_25c">While the <filename>usermap</filename> file that it 21.922 + refers to might look like this: 21.923 + </para> 21.924 + <programlisting># bugzilla-usermap.conf - inside a hg repository 21.925 +[usermap] stephanie@example.com = steph</programlisting> 21.926 + 21.927 + </sect3> 21.928 + <sect3> 21.929 + <title>Configuring the text that gets added to a bug</title> 21.930 + 21.931 + <para id="x_25d">You can configure the text that this hook adds as a 21.932 + comment; you specify it in the form of a Mercurial template. 21.933 + Several <filename role="special">~/.hgrc</filename> entries 21.934 + (still in the <literal role="rc-bugzilla">bugzilla</literal> 21.935 + section) control this behavior. 21.936 + </para> 21.937 + <itemizedlist> 21.938 + <listitem><para id="x_25e"><literal>strip</literal>: The number of 21.939 + leading path elements to strip from a repository's path 21.940 + name to construct a partial path for a URL. For example, 21.941 + if the repositories on your server live under <filename 21.942 + class="directory">/home/hg/repos</filename>, and you 21.943 + have a repository whose path is <filename 21.944 + class="directory">/home/hg/repos/app/tests</filename>, 21.945 + then setting <literal>strip</literal> to 21.946 + <literal>4</literal> will give a partial path of 21.947 + <filename class="directory">app/tests</filename>. The 21.948 + hook will make this partial path available when 21.949 + expanding a template, as <literal>webroot</literal>. 21.950 + </para> 21.951 + </listitem> 21.952 + <listitem><para id="x_25f"><literal>template</literal>: The text of the 21.953 + template to use. In addition to the usual 21.954 + changeset-related variables, this template can use 21.955 + <literal>hgweb</literal> (the value of the 21.956 + <literal>hgweb</literal> configuration item above) and 21.957 + <literal>webroot</literal> (the path constructed using 21.958 + <literal>strip</literal> above). 21.959 + </para> 21.960 + </listitem></itemizedlist> 21.961 + 21.962 + <para id="x_260">In addition, you can add a <envar 21.963 + role="rc-item-web">baseurl</envar> item to the <literal 21.964 + role="rc-web">web</literal> section of your <filename 21.965 + role="special">~/.hgrc</filename>. The <literal 21.966 + role="hg-ext">bugzilla</literal> hook will make this 21.967 + available when expanding a template, as the base string to 21.968 + use when constructing a URL that will let users browse from 21.969 + a Bugzilla comment to view a changeset. Example: 21.970 + </para> 21.971 + <programlisting>[web] 21.972 +baseurl = http://hg.domain.com/</programlisting> 21.973 + 21.974 + <para id="x_261">Here is an example set of <literal 21.975 + role="hg-ext">bugzilla</literal> hook config information. 21.976 + </para> 21.977 + 21.978 + &ch10-bugzilla-config.lst; 21.979 + 21.980 + </sect3> 21.981 + <sect3> 21.982 + <title>Testing and troubleshooting</title> 21.983 + 21.984 + <para id="x_262">The most common problems with configuring the <literal 21.985 + role="hg-ext">bugzilla</literal> hook relate to running 21.986 + Bugzilla's <filename>processmail</filename> script and 21.987 + mapping committer names to user names. 21.988 + </para> 21.989 + 21.990 + <para id="x_263">Recall from <xref 21.991 + linkend="sec:hook:bugzilla:config"/> above that the user 21.992 + that runs the Mercurial process on the server is also the 21.993 + one that will run the <filename>processmail</filename> 21.994 + script. The <filename>processmail</filename> script 21.995 + sometimes causes Bugzilla to write to files in its 21.996 + configuration directory, and Bugzilla's configuration files 21.997 + are usually owned by the user that your web server runs 21.998 + under. 21.999 + </para> 21.1000 + 21.1001 + <para id="x_264">You can cause <filename>processmail</filename> to be run 21.1002 + with the suitable user's identity using the 21.1003 + <command>sudo</command> command. Here is an example entry 21.1004 + for a <filename>sudoers</filename> file. 21.1005 + </para> 21.1006 + <programlisting>hg_user = (httpd_user) 21.1007 +NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting> 21.1008 + <para id="x_265">This allows the <literal>hg_user</literal> user to run a 21.1009 + <filename>processmail-wrapper</filename> program under the 21.1010 + identity of <literal>httpd_user</literal>. 21.1011 + </para> 21.1012 + 21.1013 + <para id="x_266">This indirection through a wrapper script is necessary, 21.1014 + because <filename>processmail</filename> expects to be run 21.1015 + with its current directory set to wherever you installed 21.1016 + Bugzilla; you can't specify that kind of constraint in a 21.1017 + <filename>sudoers</filename> file. The contents of the 21.1018 + wrapper script are simple: 21.1019 + </para> 21.1020 + <programlisting>#!/bin/sh 21.1021 +cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting> 21.1022 + <para id="x_267">It doesn't seem to matter what email address you pass to 21.1023 + <filename>processmail</filename>. 21.1024 + </para> 21.1025 + 21.1026 + <para id="x_268">If your <literal role="rc-usermap">usermap</literal> is 21.1027 + not set up correctly, users will see an error message from 21.1028 + the <literal role="hg-ext">bugzilla</literal> hook when they 21.1029 + push changes to the server. The error message will look 21.1030 + like this: 21.1031 + </para> 21.1032 + <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting> 21.1033 + <para id="x_269">What this means is that the committer's address, 21.1034 + <literal>john.q.public@example.com</literal>, is not a valid 21.1035 + Bugzilla user name, nor does it have an entry in your 21.1036 + <literal role="rc-usermap">usermap</literal> that maps it to 21.1037 + a valid Bugzilla user name. 21.1038 + </para> 21.1039 + 21.1040 + </sect3> </sect2> 21.1041 + 21.1042 + <sect2> 21.1043 + <title><literal role="hg-ext">notify</literal>&emdash;send email 21.1044 + notifications</title> 21.1045 + 21.1046 + <para id="x_26a">Although Mercurial's built-in web server provides RSS 21.1047 + feeds of changes in every repository, many people prefer to 21.1048 + receive change notifications via email. The <literal 21.1049 + role="hg-ext">notify</literal> hook lets you send out 21.1050 + notifications to a set of email addresses whenever changesets 21.1051 + arrive that those subscribers are interested in. 21.1052 + </para> 21.1053 + 21.1054 + <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal> 21.1055 + hook, the <literal role="hg-ext">notify</literal> hook is 21.1056 + template-driven, so you can customise the contents of the 21.1057 + notification messages that it sends. 21.1058 + </para> 21.1059 + 21.1060 + <para id="x_26c">By default, the <literal role="hg-ext">notify</literal> 21.1061 + hook includes a diff of every changeset that it sends out; you 21.1062 + can limit the size of the diff, or turn this feature off 21.1063 + entirely. It is useful for letting subscribers review changes 21.1064 + immediately, rather than clicking to follow a URL. 21.1065 + </para> 21.1066 + 21.1067 + <sect3> 21.1068 + <title>Configuring the <literal role="hg-ext">notify</literal> 21.1069 + hook</title> 21.1070 + 21.1071 + <para id="x_26d">You can set up the <literal 21.1072 + role="hg-ext">notify</literal> hook to send one email 21.1073 + message per incoming changeset, or one per incoming group of 21.1074 + changesets (all those that arrived in a single pull or 21.1075 + push). 21.1076 + </para> 21.1077 + <programlisting>[hooks] 21.1078 +# send one email per group of changes 21.1079 +changegroup.notify = python:hgext.notify.hook 21.1080 +# send one email per change 21.1081 +incoming.notify = python:hgext.notify.hook</programlisting> 21.1082 + 21.1083 + <para id="x_26e">Configuration information for this hook lives in the 21.1084 + <literal role="rc-notify">notify</literal> section of a 21.1085 + <filename role="special">~/.hgrc</filename> file. 21.1086 + </para> 21.1087 + <itemizedlist> 21.1088 + <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>: 21.1089 + By default, this hook does not send out email at all; 21.1090 + instead, it prints the message that it 21.1091 + <emphasis>would</emphasis> send. Set this item to 21.1092 + <literal>false</literal> to allow email to be sent. The 21.1093 + reason that sending of email is turned off by default is 21.1094 + that it takes several tries to configure this extension 21.1095 + exactly as you would like, and it would be bad form to 21.1096 + spam subscribers with a number of <quote>broken</quote> 21.1097 + notifications while you debug your configuration. 21.1098 + </para> 21.1099 + </listitem> 21.1100 + <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>: 21.1101 + The path to a configuration file that contains 21.1102 + subscription information. This is kept separate from 21.1103 + the main <filename role="special">~/.hgrc</filename> so 21.1104 + that you can maintain it in a repository of its own. 21.1105 + People can then clone that repository, update their 21.1106 + subscriptions, and push the changes back to your server. 21.1107 + </para> 21.1108 + </listitem> 21.1109 + <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>: 21.1110 + The number of leading path separator characters to strip 21.1111 + from a repository's path, when deciding whether a 21.1112 + repository has subscribers. For example, if the 21.1113 + repositories on your server live in <filename 21.1114 + class="directory">/home/hg/repos</filename>, and 21.1115 + <literal role="hg-ext">notify</literal> is considering a 21.1116 + repository named <filename 21.1117 + class="directory">/home/hg/repos/shared/test</filename>, 21.1118 + setting <envar role="rc-item-notify">strip</envar> to 21.1119 + <literal>4</literal> will cause <literal 21.1120 + role="hg-ext">notify</literal> to trim the path it 21.1121 + considers down to <filename 21.1122 + class="directory">shared/test</filename>, and it will 21.1123 + match subscribers against that. 21.1124 + </para> 21.1125 + </listitem> 21.1126 + <listitem><para id="x_272"><envar 21.1127 + role="rc-item-notify">template</envar>: The template 21.1128 + text to use when sending messages. This specifies both 21.1129 + the contents of the message header and its body. 21.1130 + </para> 21.1131 + </listitem> 21.1132 + <listitem><para id="x_273"><envar 21.1133 + role="rc-item-notify">maxdiff</envar>: The maximum 21.1134 + number of lines of diff data to append to the end of a 21.1135 + message. If a diff is longer than this, it is 21.1136 + truncated. By default, this is set to 300. Set this to 21.1137 + <literal>0</literal> to omit diffs from notification 21.1138 + emails. 21.1139 + </para> 21.1140 + </listitem> 21.1141 + <listitem><para id="x_274"><envar 21.1142 + role="rc-item-notify">sources</envar>: A list of 21.1143 + sources of changesets to consider. This lets you limit 21.1144 + <literal role="hg-ext">notify</literal> to only sending 21.1145 + out email about changes that remote users pushed into 21.1146 + this repository via a server, for example. See 21.1147 + <xref linkend="sec:hook:sources"/> for the sources you 21.1148 + can specify here. 21.1149 + </para> 21.1150 + </listitem></itemizedlist> 21.1151 + 21.1152 + <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar> 21.1153 + item in the <literal role="rc-web">web</literal> section, 21.1154 + you can use it in a template; it will be available as 21.1155 + <literal>webroot</literal>. 21.1156 + </para> 21.1157 + 21.1158 + <para id="x_276">Here is an example set of <literal 21.1159 + role="hg-ext">notify</literal> configuration information. 21.1160 + </para> 21.1161 + 21.1162 + &ch10-notify-config.lst; 21.1163 + 21.1164 + <para id="x_277">This will produce a message that looks like the 21.1165 + following: 21.1166 + </para> 21.1167 + 21.1168 + &ch10-notify-config-mail.lst; 21.1169 + 21.1170 + </sect3> 21.1171 + <sect3> 21.1172 + <title>Testing and troubleshooting</title> 21.1173 + 21.1174 + <para id="x_278">Do not forget that by default, the <literal 21.1175 + role="hg-ext">notify</literal> extension <emphasis>will not 21.1176 + send any mail</emphasis> until you explicitly configure it to do so, 21.1177 + by setting <envar role="rc-item-notify">test</envar> to 21.1178 + <literal>false</literal>. Until you do that, it simply 21.1179 + prints the message it <emphasis>would</emphasis> send. 21.1180 + </para> 21.1181 + 21.1182 + </sect3> 21.1183 + </sect2> 21.1184 + </sect1> 21.1185 + <sect1 id="sec:hook:ref"> 21.1186 + <title>Information for writers of hooks</title> 21.1187 + 21.1188 + <sect2> 21.1189 + <title>In-process hook execution</title> 21.1190 + 21.1191 + <para id="x_279">An in-process hook is called with arguments of the 21.1192 + following form: 21.1193 + </para> 21.1194 + <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting> 21.1195 + <para id="x_27a">The <literal>ui</literal> parameter is a <literal 21.1196 + role="py-mod-mercurial.ui">ui</literal> object. The 21.1197 + <literal>repo</literal> parameter is a <literal 21.1198 + role="py-mod-mercurial.localrepo">localrepository</literal> 21.1199 + object. The names and values of the 21.1200 + <literal>**kwargs</literal> parameters depend on the hook 21.1201 + being invoked, with the following common features: 21.1202 + </para> 21.1203 + <itemizedlist> 21.1204 + <listitem><para id="x_27b">If a parameter is named 21.1205 + <literal>node</literal> or <literal>parentN</literal>, it 21.1206 + will contain a hexadecimal changeset ID. The empty string 21.1207 + is used to represent <quote>null changeset ID</quote> 21.1208 + instead of a string of zeroes. 21.1209 + </para> 21.1210 + </listitem> 21.1211 + <listitem><para id="x_27c">If a parameter is named 21.1212 + <literal>url</literal>, it will contain the URL of a 21.1213 + remote repository, if that can be determined. 21.1214 + </para> 21.1215 + </listitem> 21.1216 + <listitem><para id="x_27d">Boolean-valued parameters are represented as 21.1217 + Python <literal>bool</literal> objects. 21.1218 + </para> 21.1219 + </listitem></itemizedlist> 21.1220 + 21.1221 + <para id="x_27e">An in-process hook is called without a change to the 21.1222 + process's working directory (unlike external hooks, which are 21.1223 + run in the root of the repository). It must not change the 21.1224 + process's working directory, or it will cause any calls it 21.1225 + makes into the Mercurial API to fail. 21.1226 + </para> 21.1227 + 21.1228 + <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it 21.1229 + is considered to have succeeded. If it returns a boolean 21.1230 + <quote>true</quote> value or raises an exception, it is 21.1231 + considered to have failed. A useful way to think of the 21.1232 + calling convention is <quote>tell me if you fail</quote>. 21.1233 + </para> 21.1234 + 21.1235 + <para id="x_280">Note that changeset IDs are passed into Python hooks as 21.1236 + hexadecimal strings, not the binary hashes that Mercurial's 21.1237 + APIs normally use. To convert a hash from hex to binary, use 21.1238 + the <literal>bin</literal> function. 21.1239 + </para> 21.1240 + </sect2> 21.1241 + 21.1242 + <sect2> 21.1243 + <title>External hook execution</title> 21.1244 + 21.1245 + <para id="x_281">An external hook is passed to the shell of the user 21.1246 + running Mercurial. Features of that shell, such as variable 21.1247 + substitution and command redirection, are available. The hook 21.1248 + is run in the root directory of the repository (unlike 21.1249 + in-process hooks, which are run in the same directory that 21.1250 + Mercurial was run in). 21.1251 + </para> 21.1252 + 21.1253 + <para id="x_282">Hook parameters are passed to the hook as environment 21.1254 + variables. Each environment variable's name is converted in 21.1255 + upper case and prefixed with the string 21.1256 + <quote><literal>HG_</literal></quote>. For example, if the 21.1257 + name of a parameter is <quote><literal>node</literal></quote>, 21.1258 + the name of the environment variable representing that 21.1259 + parameter will be <quote><literal>HG_NODE</literal></quote>. 21.1260 + </para> 21.1261 + 21.1262 + <para id="x_283">A boolean parameter is represented as the string 21.1263 + <quote><literal>1</literal></quote> for <quote>true</quote>, 21.1264 + <quote><literal>0</literal></quote> for <quote>false</quote>. 21.1265 + If an environment variable is named <envar>HG_NODE</envar>, 21.1266 + <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it 21.1267 + contains a changeset ID represented as a hexadecimal string. 21.1268 + The empty string is used to represent <quote>null changeset 21.1269 + ID</quote> instead of a string of zeroes. If an environment 21.1270 + variable is named <envar>HG_URL</envar>, it will contain the 21.1271 + URL of a remote repository, if that can be determined. 21.1272 + </para> 21.1273 + 21.1274 + <para id="x_284">If a hook exits with a status of zero, it is considered to 21.1275 + have succeeded. If it exits with a non-zero status, it is 21.1276 + considered to have failed. 21.1277 + </para> 21.1278 + </sect2> 21.1279 + 21.1280 + <sect2> 21.1281 + <title>Finding out where changesets come from</title> 21.1282 + 21.1283 + <para id="x_285">A hook that involves the transfer of changesets between a 21.1284 + local repository and another may be able to find out 21.1285 + information about the <quote>far side</quote>. Mercurial 21.1286 + knows <emphasis>how</emphasis> changes are being transferred, 21.1287 + and in many cases <emphasis>where</emphasis> they are being 21.1288 + transferred to or from. 21.1289 + </para> 21.1290 + 21.1291 + <sect3 id="sec:hook:sources"> 21.1292 + <title>Sources of changesets</title> 21.1293 + 21.1294 + <para id="x_286">Mercurial will tell a hook what means are, or were, used 21.1295 + to transfer changesets between repositories. This is 21.1296 + provided by Mercurial in a Python parameter named 21.1297 + <literal>source</literal>, or an environment variable named 21.1298 + <envar>HG_SOURCE</envar>. 21.1299 + </para> 21.1300 + 21.1301 + <itemizedlist> 21.1302 + <listitem><para id="x_287"><literal>serve</literal>: Changesets are 21.1303 + transferred to or from a remote repository over http or 21.1304 + ssh. 21.1305 + </para> 21.1306 + </listitem> 21.1307 + <listitem><para id="x_288"><literal>pull</literal>: Changesets are 21.1308 + being transferred via a pull from one repository into 21.1309 + another. 21.1310 + </para> 21.1311 + </listitem> 21.1312 + <listitem><para id="x_289"><literal>push</literal>: Changesets are 21.1313 + being transferred via a push from one repository into 21.1314 + another. 21.1315 + </para> 21.1316 + </listitem> 21.1317 + <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are 21.1318 + being transferred to or from a bundle. 21.1319 + </para> 21.1320 + </listitem></itemizedlist> 21.1321 + </sect3> 21.1322 + 21.1323 + <sect3 id="sec:hook:url"> 21.1324 + <title>Where changes are going&emdash;remote repository 21.1325 + URLs</title> 21.1326 + 21.1327 + <para id="x_28b">When possible, Mercurial will tell a hook the location 21.1328 + of the <quote>far side</quote> of an activity that transfers 21.1329 + changeset data between repositories. This is provided by 21.1330 + Mercurial in a Python parameter named 21.1331 + <literal>url</literal>, or an environment variable named 21.1332 + <envar>HG_URL</envar>. 21.1333 + </para> 21.1334 + 21.1335 + <para id="x_28c">This information is not always known. If a hook is 21.1336 + invoked in a repository that is being served via http or 21.1337 + ssh, Mercurial cannot tell where the remote repository is, 21.1338 + but it may know where the client is connecting from. In 21.1339 + such cases, the URL will take one of the following forms: 21.1340 + </para> 21.1341 + <itemizedlist> 21.1342 + <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote 21.1343 + ssh client, at the IP address 21.1344 + <literal>1.2.3.4</literal>. 21.1345 + </para> 21.1346 + </listitem> 21.1347 + <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote 21.1348 + http client, at the IP address 21.1349 + <literal>1.2.3.4</literal>. If the client is using SSL, 21.1350 + this will be of the form 21.1351 + <literal>remote:https:1.2.3.4</literal>. 21.1352 + </para> 21.1353 + </listitem> 21.1354 + <listitem><para id="x_28f">Empty&emdash;no information could be 21.1355 + discovered about the remote client. 21.1356 + </para> 21.1357 + </listitem></itemizedlist> 21.1358 + </sect3> 21.1359 + </sect2> 21.1360 + </sect1> 21.1361 + <sect1> 21.1362 + <title>Hook reference</title> 21.1363 + 21.1364 + <sect2 id="sec:hook:changegroup"> 21.1365 + <title><literal role="hook">changegroup</literal>&emdash;after 21.1366 + remote changesets added</title> 21.1367 + 21.1368 + <para id="x_290">This hook is run after a group of pre-existing changesets 21.1369 + has been added to the repository, for example via a <command 21.1370 + role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg 21.1371 + unbundle</command>. This hook is run once per operation 21.1372 + that added one or more changesets. This is in contrast to the 21.1373 + <literal role="hook">incoming</literal> hook, which is run 21.1374 + once per changeset, regardless of whether the changesets 21.1375 + arrive in a group. 21.1376 + </para> 21.1377 + 21.1378 + <para id="x_291">Some possible uses for this hook include kicking off an 21.1379 + automated build or test of the added changesets, updating a 21.1380 + bug database, or notifying subscribers that a repository 21.1381 + contains new changes. 21.1382 + </para> 21.1383 + 21.1384 + <para id="x_292">Parameters to this hook: 21.1385 + </para> 21.1386 + <itemizedlist> 21.1387 + <listitem><para id="x_293"><literal>node</literal>: A changeset ID. The 21.1388 + changeset ID of the first changeset in the group that was 21.1389 + added. All changesets between this and 21.1390 + <literal role="tag">tip</literal>, inclusive, were added by a single 21.1391 + <command role="hg-cmd">hg pull</command>, <command 21.1392 + role="hg-cmd">hg push</command> or <command 21.1393 + role="hg-cmd">hg unbundle</command>. 21.1394 + </para> 21.1395 + </listitem> 21.1396 + <listitem><para id="x_294"><literal>source</literal>: A 21.1397 + string. The source of these changes. See <xref 21.1398 + linkend="sec:hook:sources"/> for details. 21.1399 + </para> 21.1400 + </listitem> 21.1401 + <listitem><para id="x_295"><literal>url</literal>: A URL. The 21.1402 + location of the remote repository, if known. See <xref 21.1403 + linkend="sec:hook:url"/> for more information. 21.1404 + </para> 21.1405 + </listitem></itemizedlist> 21.1406 + 21.1407 + <para id="x_296">See also: <literal 21.1408 + role="hook">incoming</literal> (<xref 21.1409 + linkend="sec:hook:incoming"/>), <literal 21.1410 + role="hook">prechangegroup</literal> (<xref 21.1411 + linkend="sec:hook:prechangegroup"/>), <literal 21.1412 + role="hook">pretxnchangegroup</literal> (<xref 21.1413 + linkend="sec:hook:pretxnchangegroup"/>) 21.1414 + </para> 21.1415 + </sect2> 21.1416 + 21.1417 + <sect2 id="sec:hook:commit"> 21.1418 + <title><literal role="hook">commit</literal>&emdash;after a new 21.1419 + changeset is created</title> 21.1420 + 21.1421 + <para id="x_297">This hook is run after a new changeset has been created. 21.1422 + </para> 21.1423 + 21.1424 + <para id="x_298">Parameters to this hook: 21.1425 + </para> 21.1426 + <itemizedlist> 21.1427 + <listitem><para id="x_299"><literal>node</literal>: A changeset ID. The 21.1428 + changeset ID of the newly committed changeset. 21.1429 + </para> 21.1430 + </listitem> 21.1431 + <listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID. 21.1432 + The changeset ID of the first parent of the newly 21.1433 + committed changeset. 21.1434 + </para> 21.1435 + </listitem> 21.1436 + <listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID. 21.1437 + The changeset ID of the second parent of the newly 21.1438 + committed changeset. 21.1439 + </para> 21.1440 + </listitem></itemizedlist> 21.1441 + 21.1442 + <para id="x_29c">See also: <literal 21.1443 + role="hook">precommit</literal> (<xref 21.1444 + linkend="sec:hook:precommit"/>), <literal 21.1445 + role="hook">pretxncommit</literal> (<xref 21.1446 + linkend="sec:hook:pretxncommit"/>) 21.1447 + </para> 21.1448 + </sect2> 21.1449 + 21.1450 + <sect2 id="sec:hook:incoming"> 21.1451 + <title><literal role="hook">incoming</literal>&emdash;after one 21.1452 + remote changeset is added</title> 21.1453 + 21.1454 + <para id="x_29d">This hook is run after a pre-existing changeset has been 21.1455 + added to the repository, for example via a <command 21.1456 + role="hg-cmd">hg push</command>. If a group of changesets 21.1457 + was added in a single operation, this hook is called once for 21.1458 + each added changeset. 21.1459 + </para> 21.1460 + 21.1461 + <para id="x_29e">You can use this hook for the same purposes as 21.1462 + the <literal role="hook">changegroup</literal> hook (<xref 21.1463 + linkend="sec:hook:changegroup"/>); it's simply more 21.1464 + convenient sometimes to run a hook once per group of 21.1465 + changesets, while other times it's handier once per changeset. 21.1466 + </para> 21.1467 + 21.1468 + <para id="x_29f">Parameters to this hook: 21.1469 + </para> 21.1470 + <itemizedlist> 21.1471 + <listitem><para id="x_2a0"><literal>node</literal>: A changeset ID. The 21.1472 + ID of the newly added changeset. 21.1473 + </para> 21.1474 + </listitem> 21.1475 + <listitem><para id="x_2a1"><literal>source</literal>: A 21.1476 + string. The source of these changes. See <xref 21.1477 + linkend="sec:hook:sources"/> for details. 21.1478 + </para> 21.1479 + </listitem> 21.1480 + <listitem><para id="x_2a2"><literal>url</literal>: A URL. The 21.1481 + location of the remote repository, if known. See <xref 21.1482 + linkend="sec:hook:url"/> for more information. 21.1483 + </para> 21.1484 + </listitem></itemizedlist> 21.1485 + 21.1486 + <para id="x_2a3">See also: <literal 21.1487 + role="hook">changegroup</literal> (<xref 21.1488 + linkend="sec:hook:changegroup"/>) <literal 21.1489 + role="hook">prechangegroup</literal> (<xref 21.1490 + linkend="sec:hook:prechangegroup"/>), <literal 21.1491 + role="hook">pretxnchangegroup</literal> (<xref 21.1492 + linkend="sec:hook:pretxnchangegroup"/>) 21.1493 + </para> 21.1494 + </sect2> 21.1495 + 21.1496 + <sect2 id="sec:hook:outgoing"> 21.1497 + <title><literal role="hook">outgoing</literal>&emdash;after 21.1498 + changesets are propagated</title> 21.1499 + 21.1500 + <para id="x_2a4">This hook is run after a group of changesets has been 21.1501 + propagated out of this repository, for example by a <command 21.1502 + role="hg-cmd">hg push</command> or <command role="hg-cmd">hg 21.1503 + bundle</command> command. 21.1504 + </para> 21.1505 + 21.1506 + <para id="x_2a5">One possible use for this hook is to notify administrators 21.1507 + that changes have been pulled. 21.1508 + </para> 21.1509 + 21.1510 + <para id="x_2a6">Parameters to this hook: 21.1511 + </para> 21.1512 + <itemizedlist> 21.1513 + <listitem><para id="x_2a7"><literal>node</literal>: A changeset ID. The 21.1514 + changeset ID of the first changeset of the group that was 21.1515 + sent. 21.1516 + </para> 21.1517 + </listitem> 21.1518 + <listitem><para id="x_2a8"><literal>source</literal>: A string. The 21.1519 + source of the of the operation (see <xref 21.1520 + linkend="sec:hook:sources"/>). If a remote 21.1521 + client pulled changes from this repository, 21.1522 + <literal>source</literal> will be 21.1523 + <literal>serve</literal>. If the client that obtained 21.1524 + changes from this repository was local, 21.1525 + <literal>source</literal> will be 21.1526 + <literal>bundle</literal>, <literal>pull</literal>, or 21.1527 + <literal>push</literal>, depending on the operation the 21.1528 + client performed. 21.1529 + </para> 21.1530 + </listitem> 21.1531 + <listitem><para id="x_2a9"><literal>url</literal>: A URL. The 21.1532 + location of the remote repository, if known. See <xref 21.1533 + linkend="sec:hook:url"/> for more information. 21.1534 + </para> 21.1535 + </listitem></itemizedlist> 21.1536 + 21.1537 + <para id="x_2aa">See also: <literal 21.1538 + role="hook">preoutgoing</literal> (<xref 21.1539 + linkend="sec:hook:preoutgoing"/>) 21.1540 + </para> 21.1541 + </sect2> 21.1542 + 21.1543 + <sect2 id="sec:hook:prechangegroup"> 21.1544 + <title><literal 21.1545 + role="hook">prechangegroup</literal>&emdash;before starting 21.1546 + to add remote changesets</title> 21.1547 + 21.1548 + <para id="x_2ab">This controlling hook is run before Mercurial begins to 21.1549 + add a group of changesets from another repository. 21.1550 + </para> 21.1551 + 21.1552 + <para id="x_2ac">This hook does not have any information about the 21.1553 + changesets to be added, because it is run before transmission 21.1554 + of those changesets is allowed to begin. If this hook fails, 21.1555 + the changesets will not be transmitted. 21.1556 + </para> 21.1557 + 21.1558 + <para id="x_2ad">One use for this hook is to prevent external changes from 21.1559 + being added to a repository. For example, you could use this 21.1560 + to <quote>freeze</quote> a server-hosted branch temporarily or 21.1561 + permanently so that users cannot push to it, while still 21.1562 + allowing a local administrator to modify the repository. 21.1563 + </para> 21.1564 + 21.1565 + <para id="x_2ae">Parameters to this hook: 21.1566 + </para> 21.1567 + <itemizedlist> 21.1568 + <listitem><para id="x_2af"><literal>source</literal>: A string. The 21.1569 + source of these changes. See <xref 21.1570 + linkend="sec:hook:sources"/> for details. 21.1571 + </para> 21.1572 + </listitem> 21.1573 + <listitem><para id="x_2b0"><literal>url</literal>: A URL. The 21.1574 + location of the remote repository, if known. See <xref 21.1575 + linkend="sec:hook:url"/> for more information. 21.1576 + </para> 21.1577 + </listitem></itemizedlist> 21.1578 + 21.1579 + <para id="x_2b1">See also: <literal 21.1580 + role="hook">changegroup</literal> (<xref 21.1581 + linkend="sec:hook:changegroup"/>), <literal 21.1582 + role="hook">incoming</literal> (<xref 21.1583 + linkend="sec:hook:incoming"/>), <literal 21.1584 + role="hook">pretxnchangegroup</literal> (<xref 21.1585 + linkend="sec:hook:pretxnchangegroup"/>) 21.1586 + </para> 21.1587 + </sect2> 21.1588 + 21.1589 + <sect2 id="sec:hook:precommit"> 21.1590 + <title><literal role="hook">precommit</literal>&emdash;before 21.1591 + starting to commit a changeset</title> 21.1592 + 21.1593 + <para id="x_2b2">This hook is run before Mercurial begins to commit a new 21.1594 + changeset. It is run before Mercurial has any of the metadata 21.1595 + for the commit, such as the files to be committed, the commit 21.1596 + message, or the commit date. 21.1597 + </para> 21.1598 + 21.1599 + <para id="x_2b3">One use for this hook is to disable the ability to commit 21.1600 + new changesets, while still allowing incoming changesets. 21.1601 + Another is to run a build or test, and only allow the commit 21.1602 + to begin if the build or test succeeds. 21.1603 + </para> 21.1604 + 21.1605 + <para id="x_2b4">Parameters to this hook: 21.1606 + </para> 21.1607 + <itemizedlist> 21.1608 + <listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID. 21.1609 + The changeset ID of the first parent of the working 21.1610 + directory. 21.1611 + </para> 21.1612 + </listitem> 21.1613 + <listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID. 21.1614 + The changeset ID of the second parent of the working 21.1615 + directory. 21.1616 + </para> 21.1617 + </listitem></itemizedlist> 21.1618 + <para id="x_2b7">If the commit proceeds, the parents of the working 21.1619 + directory will become the parents of the new changeset. 21.1620 + </para> 21.1621 + 21.1622 + <para id="x_2b8">See also: <literal role="hook">commit</literal> 21.1623 + (<xref linkend="sec:hook:commit"/>), <literal 21.1624 + role="hook">pretxncommit</literal> (<xref 21.1625 + linkend="sec:hook:pretxncommit"/>) 21.1626 + </para> 21.1627 + </sect2> 21.1628 + 21.1629 + <sect2 id="sec:hook:preoutgoing"> 21.1630 + <title><literal role="hook">preoutgoing</literal>&emdash;before 21.1631 + starting to propagate changesets</title> 21.1632 + 21.1633 + <para id="x_2b9">This hook is invoked before Mercurial knows the identities 21.1634 + of the changesets to be transmitted. 21.1635 + </para> 21.1636 + 21.1637 + <para id="x_2ba">One use for this hook is to prevent changes from being 21.1638 + transmitted to another repository. 21.1639 + </para> 21.1640 + 21.1641 + <para id="x_2bb">Parameters to this hook: 21.1642 + </para> 21.1643 + <itemizedlist> 21.1644 + <listitem><para id="x_2bc"><literal>source</literal>: A 21.1645 + string. The source of the operation that is attempting to 21.1646 + obtain changes from this repository (see <xref 21.1647 + linkend="sec:hook:sources"/>). See the documentation 21.1648 + for the <literal>source</literal> parameter to the 21.1649 + <literal role="hook">outgoing</literal> hook, in 21.1650 + <xref linkend="sec:hook:outgoing"/>, for possible values 21.1651 + of this parameter. 21.1652 + </para> 21.1653 + </listitem> 21.1654 + <listitem><para id="x_2bd"><literal>url</literal>: A URL. The 21.1655 + location of the remote repository, if known. See <xref 21.1656 + linkend="sec:hook:url"/> for more information. 21.1657 + </para> 21.1658 + </listitem></itemizedlist> 21.1659 + 21.1660 + <para id="x_2be">See also: <literal 21.1661 + role="hook">outgoing</literal> (<xref 21.1662 + linkend="sec:hook:outgoing"/>) 21.1663 + </para> 21.1664 + </sect2> 21.1665 + 21.1666 + <sect2 id="sec:hook:pretag"> 21.1667 + <title><literal role="hook">pretag</literal>&emdash;before 21.1668 + tagging a changeset</title> 21.1669 + 21.1670 + <para id="x_2bf">This controlling hook is run before a tag is created. If 21.1671 + the hook succeeds, creation of the tag proceeds. If the hook 21.1672 + fails, the tag is not created. 21.1673 + </para> 21.1674 + 21.1675 + <para id="x_2c0">Parameters to this hook: 21.1676 + </para> 21.1677 + <itemizedlist> 21.1678 + <listitem><para id="x_2c1"><literal>local</literal>: A boolean. Whether 21.1679 + the tag is local to this repository instance (i.e. stored 21.1680 + in <filename role="special">.hg/localtags</filename>) or 21.1681 + managed by Mercurial (stored in <filename 21.1682 + role="special">.hgtags</filename>). 21.1683 + </para> 21.1684 + </listitem> 21.1685 + <listitem><para id="x_2c2"><literal>node</literal>: A changeset ID. The 21.1686 + ID of the changeset to be tagged. 21.1687 + </para> 21.1688 + </listitem> 21.1689 + <listitem><para id="x_2c3"><literal>tag</literal>: A string. The name of 21.1690 + the tag to be created. 21.1691 + </para> 21.1692 + </listitem></itemizedlist> 21.1693 + 21.1694 + <para id="x_2c4">If the tag to be created is 21.1695 + revision-controlled, the <literal 21.1696 + role="hook">precommit</literal> and <literal 21.1697 + role="hook">pretxncommit</literal> hooks (<xref 21.1698 + linkend="sec:hook:commit"/> and <xref 21.1699 + linkend="sec:hook:pretxncommit"/>) will also be run. 21.1700 + </para> 21.1701 + 21.1702 + <para id="x_2c5">See also: <literal role="hook">tag</literal> 21.1703 + (<xref linkend="sec:hook:tag"/>) 21.1704 + </para> 21.1705 + </sect2> 21.1706 + 21.1707 + <sect2 id="sec:hook:pretxnchangegroup"> 21.1708 + <title><literal 21.1709 + role="hook">pretxnchangegroup</literal>&emdash;before 21.1710 + completing addition of remote changesets</title> 21.1711 + 21.1712 + <para id="x_2c6">This controlling hook is run before a 21.1713 + transaction&emdash;that manages the addition of a group of new 21.1714 + changesets from outside the repository&emdash;completes. If 21.1715 + the hook succeeds, the transaction completes, and all of the 21.1716 + changesets become permanent within this repository. If the 21.1717 + hook fails, the transaction is rolled back, and the data for 21.1718 + the changesets is erased. 21.1719 + </para> 21.1720 + 21.1721 + <para id="x_2c7">This hook can access the metadata associated with the 21.1722 + almost-added changesets, but it should not do anything 21.1723 + permanent with this data. It must also not modify the working 21.1724 + directory. 21.1725 + </para> 21.1726 + 21.1727 + <para id="x_2c8">While this hook is running, if other Mercurial processes 21.1728 + access this repository, they will be able to see the 21.1729 + almost-added changesets as if they are permanent. This may 21.1730 + lead to race conditions if you do not take steps to avoid 21.1731 + them. 21.1732 + </para> 21.1733 + 21.1734 + <para id="x_2c9">This hook can be used to automatically vet a group of 21.1735 + changesets. If the hook fails, all of the changesets are 21.1736 + <quote>rejected</quote> when the transaction rolls back. 21.1737 + </para> 21.1738 + 21.1739 + <para id="x_2ca">Parameters to this hook: 21.1740 + </para> 21.1741 + <itemizedlist> 21.1742 + <listitem><para id="x_2cb"><literal>node</literal>: A changeset ID. The 21.1743 + changeset ID of the first changeset in the group that was 21.1744 + added. All changesets between this and 21.1745 + <literal role="tag">tip</literal>, 21.1746 + inclusive, were added by a single <command 21.1747 + role="hg-cmd">hg pull</command>, <command 21.1748 + role="hg-cmd">hg push</command> or <command 21.1749 + role="hg-cmd">hg unbundle</command>. 21.1750 + </para> 21.1751 + </listitem> 21.1752 + <listitem><para id="x_2cc"><literal>source</literal>: A 21.1753 + string. The source of these changes. See <xref 21.1754 + linkend="sec:hook:sources"/> for details. 21.1755 + </para> 21.1756 + </listitem> 21.1757 + <listitem><para id="x_2cd"><literal>url</literal>: A URL. The 21.1758 + location of the remote repository, if known. See <xref 21.1759 + linkend="sec:hook:url"/> for more information. 21.1760 + </para> 21.1761 + </listitem></itemizedlist> 21.1762 + 21.1763 + <para id="x_2ce">See also: <literal 21.1764 + role="hook">changegroup</literal> (<xref 21.1765 + linkend="sec:hook:changegroup"/>), <literal 21.1766 + role="hook">incoming</literal> (<xref 21.1767 + linkend="sec:hook:incoming"/>), <literal 21.1768 + role="hook">prechangegroup</literal> (<xref 21.1769 + linkend="sec:hook:prechangegroup"/>) 21.1770 + </para> 21.1771 + </sect2> 21.1772 + 21.1773 + <sect2 id="sec:hook:pretxncommit"> 21.1774 + <title><literal role="hook">pretxncommit</literal>&emdash;before 21.1775 + completing commit of new changeset</title> 21.1776 + 21.1777 + <para id="x_2cf">This controlling hook is run before a 21.1778 + transaction&emdash;that manages a new commit&emdash;completes. 21.1779 + If the hook succeeds, the transaction completes and the 21.1780 + changeset becomes permanent within this repository. If the 21.1781 + hook fails, the transaction is rolled back, and the commit 21.1782 + data is erased. 21.1783 + </para> 21.1784 + 21.1785 + <para id="x_2d0">This hook can access the metadata associated with the 21.1786 + almost-new changeset, but it should not do anything permanent 21.1787 + with this data. It must also not modify the working 21.1788 + directory. 21.1789 + </para> 21.1790 + 21.1791 + <para id="x_2d1">While this hook is running, if other Mercurial processes 21.1792 + access this repository, they will be able to see the 21.1793 + almost-new changeset as if it is permanent. This may lead to 21.1794 + race conditions if you do not take steps to avoid them. 21.1795 + </para> 21.1796 + 21.1797 + <para id="x_2d2">Parameters to this hook:</para> 21.1798 + 21.1799 + <itemizedlist> 21.1800 + <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The 21.1801 + changeset ID of the newly committed changeset. 21.1802 + </para> 21.1803 + </listitem> 21.1804 + <listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID. 21.1805 + The changeset ID of the first parent of the newly 21.1806 + committed changeset. 21.1807 + </para> 21.1808 + </listitem> 21.1809 + <listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID. 21.1810 + The changeset ID of the second parent of the newly 21.1811 + committed changeset. 21.1812 + </para> 21.1813 + </listitem></itemizedlist> 21.1814 + 21.1815 + <para id="x_2d6">See also: <literal 21.1816 + role="hook">precommit</literal> (<xref 21.1817 + linkend="sec:hook:precommit"/>) 21.1818 + </para> 21.1819 + </sect2> 21.1820 + 21.1821 + <sect2 id="sec:hook:preupdate"> 21.1822 + <title><literal role="hook">preupdate</literal>&emdash;before 21.1823 + updating or merging working directory</title> 21.1824 + 21.1825 + <para id="x_2d7">This controlling hook is run before an update 21.1826 + or merge of the working directory begins. It is run only if 21.1827 + Mercurial's normal pre-update checks determine that the update 21.1828 + or merge can proceed. If the hook succeeds, the update or 21.1829 + merge may proceed; if it fails, the update or merge does not 21.1830 + start. 21.1831 + </para> 21.1832 + 21.1833 + <para id="x_2d8">Parameters to this hook: 21.1834 + </para> 21.1835 + <itemizedlist> 21.1836 + <listitem><para id="x_2d9"><literal>parent1</literal>: A 21.1837 + changeset ID. The ID of the parent that the working 21.1838 + directory is to be updated to. If the working directory 21.1839 + is being merged, it will not change this parent. 21.1840 + </para> 21.1841 + </listitem> 21.1842 + <listitem><para id="x_2da"><literal>parent2</literal>: A 21.1843 + changeset ID. Only set if the working directory is being 21.1844 + merged. The ID of the revision that the working directory 21.1845 + is being merged with. 21.1846 + </para> 21.1847 + </listitem></itemizedlist> 21.1848 + 21.1849 + <para id="x_2db">See also: <literal role="hook">update</literal> 21.1850 + (<xref linkend="sec:hook:update"/>)</para> 21.1851 + </sect2> 21.1852 + 21.1853 + <sect2 id="sec:hook:tag"> 21.1854 + <title><literal role="hook">tag</literal>&emdash;after tagging a 21.1855 + changeset</title> 21.1856 + 21.1857 + <para id="x_2dc">This hook is run after a tag has been created. 21.1858 + </para> 21.1859 + 21.1860 + <para id="x_2dd">Parameters to this hook: 21.1861 + </para> 21.1862 + <itemizedlist> 21.1863 + <listitem><para id="x_2de"><literal>local</literal>: A boolean. Whether 21.1864 + the new tag is local to this repository instance (i.e. 21.1865 + stored in <filename 21.1866 + role="special">.hg/localtags</filename>) or managed by 21.1867 + Mercurial (stored in <filename 21.1868 + role="special">.hgtags</filename>). 21.1869 + </para> 21.1870 + </listitem> 21.1871 + <listitem><para id="x_2df"><literal>node</literal>: A changeset ID. The 21.1872 + ID of the changeset that was tagged. 21.1873 + </para> 21.1874 + </listitem> 21.1875 + <listitem><para id="x_2e0"><literal>tag</literal>: A string. The name of 21.1876 + the tag that was created. 21.1877 + </para> 21.1878 + </listitem></itemizedlist> 21.1879 + 21.1880 + <para id="x_2e1">If the created tag is revision-controlled, the <literal 21.1881 + role="hook">commit</literal> hook (section <xref 21.1882 + linkend="sec:hook:commit"/>) is run before this hook. 21.1883 + </para> 21.1884 + 21.1885 + <para id="x_2e2">See also: <literal role="hook">pretag</literal> 21.1886 + (<xref linkend="sec:hook:pretag"/>) 21.1887 + </para> 21.1888 + </sect2> 21.1889 + 21.1890 + <sect2 id="sec:hook:update"> 21.1891 + <title><literal role="hook">update</literal>&emdash;after 21.1892 + updating or merging working directory</title> 21.1893 + 21.1894 + <para id="x_2e3">This hook is run after an update or merge of the working 21.1895 + directory completes. Since a merge can fail (if the external 21.1896 + <command>hgmerge</command> command fails to resolve conflicts 21.1897 + in a file), this hook communicates whether the update or merge 21.1898 + completed cleanly. 21.1899 + </para> 21.1900 + 21.1901 + <itemizedlist> 21.1902 + <listitem><para id="x_2e4"><literal>error</literal>: A boolean. 21.1903 + Indicates whether the update or merge completed 21.1904 + successfully. 21.1905 + </para> 21.1906 + </listitem> 21.1907 + <listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID. 21.1908 + The ID of the parent that the working directory was 21.1909 + updated to. If the working directory was merged, it will 21.1910 + not have changed this parent. 21.1911 + </para> 21.1912 + </listitem> 21.1913 + <listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID. 21.1914 + Only set if the working directory was merged. The ID of 21.1915 + the revision that the working directory was merged with. 21.1916 + </para> 21.1917 + </listitem></itemizedlist> 21.1918 + 21.1919 + <para id="x_2e7">See also: <literal role="hook">preupdate</literal> 21.1920 + (<xref linkend="sec:hook:preupdate"/>) 21.1921 + </para> 21.1922 + 21.1923 + </sect2> 21.1924 + </sect1> 21.1925 +</chapter> 21.1926 + 21.1927 +<!-- 21.1928 +local variables: 21.1929 +sgml-parent-document: ("00book.xml" "book" "chapter") 21.1930 +end: 21.1931 +-->
22.1 --- a/en/ch10-template.xml Thu May 07 21:06:49 2009 -0700 22.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 22.3 @@ -1,685 +0,0 @@ 22.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 22.5 - 22.6 -<chapter id="chap:template"> 22.7 - <?dbhtml filename="customizing-the-output-of-mercurial.html"?> 22.8 - <title>Customizing the output of Mercurial</title> 22.9 - 22.10 - <para id="x_578">Mercurial provides a powerful mechanism to let you control how 22.11 - it displays information. The mechanism is based on templates. 22.12 - You can use templates to generate specific output for a single 22.13 - command, or to customize the entire appearance of the built-in web 22.14 - interface.</para> 22.15 - 22.16 - <sect1 id="sec:style"> 22.17 - <title>Using precanned output styles</title> 22.18 - 22.19 - <para id="x_579">Packaged with Mercurial are some output styles that you can 22.20 - use immediately. A style is simply a precanned template that 22.21 - someone wrote and installed somewhere that Mercurial can 22.22 - find.</para> 22.23 - 22.24 - <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's 22.25 - review its normal output.</para> 22.26 - 22.27 - &interaction.template.simple.normal; 22.28 - 22.29 - <para id="x_57b">This is somewhat informative, but it takes up a lot of 22.30 - space&emdash;five lines of output per changeset. The 22.31 - <literal>compact</literal> style reduces this to three lines, 22.32 - presented in a sparse manner.</para> 22.33 - 22.34 - &interaction.template.simple.compact; 22.35 - 22.36 - <para id="x_57c">The <literal>changelog</literal> style hints at the 22.37 - expressive power of Mercurial's templating engine. This style 22.38 - attempts to follow the GNU Project's changelog 22.39 - guidelines<citation>web:changelog</citation>.</para> 22.40 - 22.41 - &interaction.template.simple.changelog; 22.42 - 22.43 - <para id="x_57d">You will not be shocked to learn that Mercurial's default 22.44 - output style is named <literal>default</literal>.</para> 22.45 - 22.46 - <sect2> 22.47 - <title>Setting a default style</title> 22.48 - 22.49 - <para id="x_57e">You can modify the output style that Mercurial will use 22.50 - for every command by editing your <filename 22.51 - role="special">~/.hgrc</filename> file, naming the style 22.52 - you would prefer to use.</para> 22.53 - 22.54 - <programlisting>[ui] 22.55 -style = compact</programlisting> 22.56 - 22.57 - <para id="x_57f">If you write a style of your own, you can use it by either 22.58 - providing the path to your style file, or copying your style 22.59 - file into a location where Mercurial can find it (typically 22.60 - the <literal>templates</literal> subdirectory of your 22.61 - Mercurial install directory).</para> 22.62 - </sect2> 22.63 - </sect1> 22.64 - 22.65 - <sect1> 22.66 - <title>Commands that support styles and templates</title> 22.67 - 22.68 - <para id="x_580">All of Mercurial's 22.69 - <quote><literal>log</literal>-like</quote> commands let you use 22.70 - styles and templates: <command role="hg-cmd">hg 22.71 - incoming</command>, <command role="hg-cmd">hg log</command>, 22.72 - <command role="hg-cmd">hg outgoing</command>, and <command 22.73 - role="hg-cmd">hg tip</command>.</para> 22.74 - 22.75 - <para id="x_581">As I write this manual, these are so far the only commands 22.76 - that support styles and templates. Since these are the most 22.77 - important commands that need customizable output, there has been 22.78 - little pressure from the Mercurial user community to add style 22.79 - and template support to other commands.</para> 22.80 - </sect1> 22.81 - 22.82 - <sect1> 22.83 - <title>The basics of templating</title> 22.84 - 22.85 - <para id="x_582">At its simplest, a Mercurial template is a piece of text. 22.86 - Some of the text never changes, while other parts are 22.87 - <emphasis>expanded</emphasis>, or replaced with new text, when 22.88 - necessary.</para> 22.89 - 22.90 - <para id="x_583">Before we continue, let's look again at a simple example of 22.91 - Mercurial's normal output.</para> 22.92 - 22.93 - &interaction.template.simple.normal; 22.94 - 22.95 - <para id="x_584">Now, let's run the same command, but using a template to 22.96 - change its output.</para> 22.97 - 22.98 - &interaction.template.simple.simplest; 22.99 - 22.100 - <para id="x_585">The example above illustrates the simplest possible 22.101 - template; it's just a piece of static text, printed once for 22.102 - each changeset. The <option 22.103 - role="hg-opt-log">--template</option> option to the <command 22.104 - role="hg-cmd">hg log</command> command tells Mercurial to use 22.105 - the given text as the template when printing each 22.106 - changeset.</para> 22.107 - 22.108 - <para id="x_586">Notice that the template string above ends with the text 22.109 - <quote><literal>\n</literal></quote>. This is an 22.110 - <emphasis>escape sequence</emphasis>, telling Mercurial to print 22.111 - a newline at the end of each template item. If you omit this 22.112 - newline, Mercurial will run each piece of output together. See 22.113 - <xref linkend="sec:template:escape"/> for more details 22.114 - of escape sequences.</para> 22.115 - 22.116 - <para id="x_587">A template that prints a fixed string of text all the time 22.117 - isn't very useful; let's try something a bit more 22.118 - complex.</para> 22.119 - 22.120 - &interaction.template.simple.simplesub; 22.121 - 22.122 - <para id="x_588">As you can see, the string 22.123 - <quote><literal>{desc}</literal></quote> in the template has 22.124 - been replaced in the output with the description of each 22.125 - changeset. Every time Mercurial finds text enclosed in curly 22.126 - braces (<quote><literal>{</literal></quote> and 22.127 - <quote><literal>}</literal></quote>), it will try to replace the 22.128 - braces and text with the expansion of whatever is inside. To 22.129 - print a literal curly brace, you must escape it, as described in 22.130 - <xref linkend="sec:template:escape"/>.</para> 22.131 - </sect1> 22.132 - 22.133 - <sect1 id="sec:template:keyword"> 22.134 - <title>Common template keywords</title> 22.135 - 22.136 - <para id="x_589">You can start writing simple templates immediately using the 22.137 - keywords below.</para> 22.138 - 22.139 - <itemizedlist> 22.140 - <listitem><para id="x_58a"><literal 22.141 - role="template-keyword">author</literal>: String. The 22.142 - unmodified author of the changeset.</para> 22.143 - </listitem> 22.144 - <listitem><para id="x_58b"><literal 22.145 - role="template-keyword">branches</literal>: String. The 22.146 - name of the branch on which the changeset was committed. 22.147 - Will be empty if the branch name was 22.148 - <literal>default</literal>.</para> 22.149 - </listitem> 22.150 - <listitem><para id="x_58c"><literal role="template-keyword">date</literal>: 22.151 - Date information. The date when the changeset was 22.152 - committed. This is <emphasis>not</emphasis> human-readable; 22.153 - you must pass it through a filter that will render it 22.154 - appropriately. See <xref 22.155 - linkend="sec:template:filter"/> for more information 22.156 - on filters. The date is expressed as a pair of numbers. The 22.157 - first number is a Unix UTC timestamp (seconds since January 22.158 - 1, 1970); the second is the offset of the committer's 22.159 - timezone from UTC, in seconds.</para> 22.160 - </listitem> 22.161 - <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>: 22.162 - String. The text of the changeset description.</para> 22.163 - </listitem> 22.164 - <listitem><para id="x_58e"><literal 22.165 - role="template-keyword">files</literal>: List of strings. 22.166 - All files modified, added, or removed by this 22.167 - changeset.</para> 22.168 - </listitem> 22.169 - <listitem><para id="x_58f"><literal 22.170 - role="template-keyword">file_adds</literal>: List of 22.171 - strings. Files added by this changeset.</para> 22.172 - </listitem> 22.173 - <listitem><para id="x_590"><literal 22.174 - role="template-keyword">file_dels</literal>: List of 22.175 - strings. Files removed by this changeset.</para> 22.176 - </listitem> 22.177 - <listitem><para id="x_591"><literal role="template-keyword">node</literal>: 22.178 - String. The changeset identification hash, as a 22.179 - 40-character hexadecimal string.</para> 22.180 - </listitem> 22.181 - <listitem><para id="x_592"><literal 22.182 - role="template-keyword">parents</literal>: List of 22.183 - strings. The parents of the changeset.</para> 22.184 - </listitem> 22.185 - <listitem><para id="x_593"><literal role="template-keyword">rev</literal>: 22.186 - Integer. The repository-local changeset revision 22.187 - number.</para> 22.188 - </listitem> 22.189 - <listitem><para id="x_594"><literal role="template-keyword">tags</literal>: 22.190 - List of strings. Any tags associated with the 22.191 - changeset.</para> 22.192 - </listitem> 22.193 - </itemizedlist> 22.194 - 22.195 - <para id="x_595">A few simple experiments will show us what to expect when we 22.196 - use these keywords; you can see the results below.</para> 22.197 - 22.198 - &interaction.template.simple.keywords; 22.199 - 22.200 - <para id="x_596">As we noted above, the date keyword does not produce 22.201 - human-readable output, so we must treat it specially. This 22.202 - involves using a <emphasis>filter</emphasis>, about which more 22.203 - in <xref linkend="sec:template:filter"/>.</para> 22.204 - 22.205 - &interaction.template.simple.datekeyword; 22.206 - </sect1> 22.207 - 22.208 - <sect1 id="sec:template:escape"> 22.209 - <title>Escape sequences</title> 22.210 - 22.211 - <para id="x_597">Mercurial's templating engine recognises the most commonly 22.212 - used escape sequences in strings. When it sees a backslash 22.213 - (<quote><literal>\</literal></quote>) character, it looks at the 22.214 - following character and substitutes the two characters with a 22.215 - single replacement, as described below.</para> 22.216 - 22.217 - <itemizedlist> 22.218 - <listitem><para id="x_598"><literal>\</literal>: 22.219 - Backslash, <quote><literal>\</literal></quote>, ASCII 22.220 - 134.</para> 22.221 - </listitem> 22.222 - <listitem><para id="x_599"><literal>\n</literal>: Newline, 22.223 - ASCII 12.</para> 22.224 - </listitem> 22.225 - <listitem><para id="x_59a"><literal>\r</literal>: Carriage 22.226 - return, ASCII 15.</para> 22.227 - </listitem> 22.228 - <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII 22.229 - 11.</para> 22.230 - </listitem> 22.231 - <listitem><para id="x_59c"><literal>\v</literal>: Vertical 22.232 - tab, ASCII 13.</para> 22.233 - </listitem> 22.234 - <listitem><para id="x_59d"><literal>\{</literal>: Open curly 22.235 - brace, <quote><literal>{</literal></quote>, ASCII 22.236 - 173.</para> 22.237 - </listitem> 22.238 - <listitem><para id="x_59e"><literal>\}</literal>: Close curly 22.239 - brace, <quote><literal>}</literal></quote>, ASCII 22.240 - 175.</para> 22.241 - </listitem></itemizedlist> 22.242 - 22.243 - <para id="x_59f">As indicated above, if you want the expansion of a template 22.244 - to contain a literal <quote><literal>\</literal></quote>, 22.245 - <quote><literal>{</literal></quote>, or 22.246 - <quote><literal>{</literal></quote> character, you must escape 22.247 - it.</para> 22.248 - </sect1> 22.249 - 22.250 - <sect1 id="sec:template:filter"> 22.251 - <title>Filtering keywords to change their results</title> 22.252 - 22.253 - <para id="x_5a0">Some of the results of template expansion are not 22.254 - immediately easy to use. Mercurial lets you specify an optional 22.255 - chain of <emphasis>filters</emphasis> to modify the result of 22.256 - expanding a keyword. You have already seen a common filter, 22.257 - <literal role="template-kw-filt-date">isodate</literal>, in 22.258 - action above, to make a date readable.</para> 22.259 - 22.260 - <para id="x_5a1">Below is a list of the most commonly used filters that 22.261 - Mercurial supports. While some filters can be applied to any 22.262 - text, others can only be used in specific circumstances. The 22.263 - name of each filter is followed first by an indication of where 22.264 - it can be used, then a description of its effect.</para> 22.265 - 22.266 - <itemizedlist> 22.267 - <listitem><para id="x_5a2"><literal 22.268 - role="template-filter">addbreaks</literal>: Any text. Add 22.269 - an XHTML <quote><literal><br/></literal></quote> tag 22.270 - before the end of every line except the last. For example, 22.271 - <quote><literal>foo\nbar</literal></quote> becomes 22.272 - <quote><literal>foo<br/>\nbar</literal></quote>.</para> 22.273 - </listitem> 22.274 - <listitem><para id="x_5a3"><literal 22.275 - role="template-kw-filt-date">age</literal>: <literal 22.276 - role="template-keyword">date</literal> keyword. Render 22.277 - the age of the date, relative to the current time. Yields a 22.278 - string like <quote><literal>10 22.279 - minutes</literal></quote>.</para> 22.280 - </listitem> 22.281 - <listitem><para id="x_5a4"><literal 22.282 - role="template-filter">basename</literal>: Any text, but 22.283 - most useful for the <literal 22.284 - role="template-keyword">files</literal> keyword and its 22.285 - relatives. Treat the text as a path, and return the 22.286 - basename. For example, 22.287 - <quote><literal>foo/bar/baz</literal></quote> becomes 22.288 - <quote><literal>baz</literal></quote>.</para> 22.289 - </listitem> 22.290 - <listitem><para id="x_5a5"><literal 22.291 - role="template-kw-filt-date">date</literal>: <literal 22.292 - role="template-keyword">date</literal> keyword. Render a 22.293 - date in a similar format to the Unix <literal 22.294 - role="template-keyword">date</literal> command, but with 22.295 - timezone included. Yields a string like <quote><literal>Mon 22.296 - Sep 04 15:13:13 2006 -0700</literal></quote>.</para> 22.297 - </listitem> 22.298 - <listitem><para id="x_5a6"><literal 22.299 - role="template-kw-filt-author">domain</literal>: Any text, 22.300 - but most useful for the <literal 22.301 - role="template-keyword">author</literal> keyword. Finds 22.302 - the first string that looks like an email address, and 22.303 - extract just the domain component. For example, 22.304 - <quote><literal>Bryan O'Sullivan 22.305 - <bos@serpentine.com></literal></quote> becomes 22.306 - <quote><literal>serpentine.com</literal></quote>.</para> 22.307 - </listitem> 22.308 - <listitem><para id="x_5a7"><literal 22.309 - role="template-kw-filt-author">email</literal>: Any text, 22.310 - but most useful for the <literal 22.311 - role="template-keyword">author</literal> keyword. Extract 22.312 - the first string that looks like an email address. For 22.313 - example, <quote><literal>Bryan O'Sullivan 22.314 - <bos@serpentine.com></literal></quote> becomes 22.315 - <quote><literal>bos@serpentine.com</literal></quote>.</para> 22.316 - </listitem> 22.317 - <listitem><para id="x_5a8"><literal 22.318 - role="template-filter">escape</literal>: Any text. 22.319 - Replace the special XML/XHTML characters 22.320 - <quote><literal>&</literal></quote>, 22.321 - <quote><literal><</literal></quote> and 22.322 - <quote><literal>></literal></quote> with XML 22.323 - entities.</para> 22.324 - </listitem> 22.325 - <listitem><para id="x_5a9"><literal 22.326 - role="template-filter">fill68</literal>: Any text. Wrap 22.327 - the text to fit in 68 columns. This is useful before you 22.328 - pass text through the <literal 22.329 - role="template-filter">tabindent</literal> filter, and 22.330 - still want it to fit in an 80-column fixed-font 22.331 - window.</para> 22.332 - </listitem> 22.333 - <listitem><para id="x_5aa"><literal 22.334 - role="template-filter">fill76</literal>: Any text. Wrap 22.335 - the text to fit in 76 columns.</para> 22.336 - </listitem> 22.337 - <listitem><para id="x_5ab"><literal 22.338 - role="template-filter">firstline</literal>: Any text. 22.339 - Yield the first line of text, without any trailing 22.340 - newlines.</para> 22.341 - </listitem> 22.342 - <listitem><para id="x_5ac"><literal 22.343 - role="template-kw-filt-date">hgdate</literal>: <literal 22.344 - role="template-keyword">date</literal> keyword. Render 22.345 - the date as a pair of readable numbers. Yields a string 22.346 - like <quote><literal>1157407993 22.347 - 25200</literal></quote>.</para> 22.348 - </listitem> 22.349 - <listitem><para id="x_5ad"><literal 22.350 - role="template-kw-filt-date">isodate</literal>: <literal 22.351 - role="template-keyword">date</literal> keyword. Render 22.352 - the date as a text string in ISO 8601 format. Yields a 22.353 - string like <quote><literal>2006-09-04 15:13:13 22.354 - -0700</literal></quote>.</para> 22.355 - </listitem> 22.356 - <listitem><para id="x_5ae"><literal 22.357 - role="template-filter">obfuscate</literal>: Any text, but 22.358 - most useful for the <literal 22.359 - role="template-keyword">author</literal> keyword. Yield 22.360 - the input text rendered as a sequence of XML entities. This 22.361 - helps to defeat some particularly stupid screen-scraping 22.362 - email harvesting spambots.</para> 22.363 - </listitem> 22.364 - <listitem><para id="x_5af"><literal 22.365 - role="template-kw-filt-author">person</literal>: Any text, 22.366 - but most useful for the <literal 22.367 - role="template-keyword">author</literal> keyword. Yield 22.368 - the text before an email address. For example, 22.369 - <quote><literal>Bryan O'Sullivan 22.370 - <bos@serpentine.com></literal></quote> becomes 22.371 - <quote><literal>Bryan O'Sullivan</literal></quote>.</para> 22.372 - </listitem> 22.373 - <listitem><para id="x_5b0"><literal 22.374 - role="template-kw-filt-date">rfc822date</literal>: 22.375 - <literal role="template-keyword">date</literal> keyword. 22.376 - Render a date using the same format used in email headers. 22.377 - Yields a string like <quote><literal>Mon, 04 Sep 2006 22.378 - 15:13:13 -0700</literal></quote>.</para> 22.379 - </listitem> 22.380 - <listitem><para id="x_5b1"><literal 22.381 - role="template-kw-filt-node">short</literal>: Changeset 22.382 - hash. Yield the short form of a changeset hash, i.e. a 22.383 - 12-character hexadecimal string.</para> 22.384 - </listitem> 22.385 - <listitem><para id="x_5b2"><literal 22.386 - role="template-kw-filt-date">shortdate</literal>: <literal 22.387 - role="template-keyword">date</literal> keyword. Render 22.388 - the year, month, and day of the date. Yields a string like 22.389 - <quote><literal>2006-09-04</literal></quote>.</para> 22.390 - </listitem> 22.391 - <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>: 22.392 - Any text. Strip all leading and trailing whitespace from 22.393 - the string.</para> 22.394 - </listitem> 22.395 - <listitem><para id="x_5b4"><literal 22.396 - role="template-filter">tabindent</literal>: Any text. 22.397 - Yield the text, with every line except the first starting 22.398 - with a tab character.</para> 22.399 - </listitem> 22.400 - <listitem><para id="x_5b5"><literal 22.401 - role="template-filter">urlescape</literal>: Any text. 22.402 - Escape all characters that are considered 22.403 - <quote>special</quote> by URL parsers. For example, 22.404 - <literal>foo bar</literal> becomes 22.405 - <literal>foo%20bar</literal>.</para> 22.406 - </listitem> 22.407 - <listitem><para id="x_5b6"><literal 22.408 - role="template-kw-filt-author">user</literal>: Any text, 22.409 - but most useful for the <literal 22.410 - role="template-keyword">author</literal> keyword. Return 22.411 - the <quote>user</quote> portion of an email address. For 22.412 - example, <quote><literal>Bryan O'Sullivan 22.413 - <bos@serpentine.com></literal></quote> becomes 22.414 - <quote><literal>bos</literal></quote>.</para> 22.415 - </listitem> 22.416 - </itemizedlist> 22.417 - 22.418 - &interaction.template.simple.manyfilters; 22.419 - 22.420 - <note> 22.421 - <para id="x_5b7"> If you try to apply a filter to a piece of data that it 22.422 - cannot process, Mercurial will fail and print a Python 22.423 - exception. For example, trying to run the output of the 22.424 - <literal role="template-keyword">desc</literal> keyword into 22.425 - the <literal role="template-kw-filt-date">isodate</literal> 22.426 - filter is not a good idea.</para> 22.427 - </note> 22.428 - 22.429 - <sect2> 22.430 - <title>Combining filters</title> 22.431 - 22.432 - <para id="x_5b8">It is easy to combine filters to yield output in the form 22.433 - you would like. The following chain of filters tidies up a 22.434 - description, then makes sure that it fits cleanly into 68 22.435 - columns, then indents it by a further 8 characters (at least 22.436 - on Unix-like systems, where a tab is conventionally 8 22.437 - characters wide).</para> 22.438 - 22.439 - &interaction.template.simple.combine; 22.440 - 22.441 - <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a 22.442 - tab character) in the template to force the first line to be 22.443 - indented; this is necessary since <literal 22.444 - role="template-keyword">tabindent</literal> indents all 22.445 - lines <emphasis>except</emphasis> the first.</para> 22.446 - 22.447 - <para id="x_5ba">Keep in mind that the order of filters in a chain is 22.448 - significant. The first filter is applied to the result of the 22.449 - keyword; the second to the result of the first filter; and so 22.450 - on. For example, using <literal>fill68|tabindent</literal> 22.451 - gives very different results from 22.452 - <literal>tabindent|fill68</literal>.</para> 22.453 - </sect2> 22.454 - </sect1> 22.455 - 22.456 - <sect1> 22.457 - <title>From templates to styles</title> 22.458 - 22.459 - <para id="x_5bb">A command line template provides a quick and simple way to 22.460 - format some output. Templates can become verbose, though, and 22.461 - it's useful to be able to give a template a name. A style file 22.462 - is a template with a name, stored in a file.</para> 22.463 - 22.464 - <para id="x_5bc">More than that, using a style file unlocks the power of 22.465 - Mercurial's templating engine in ways that are not possible 22.466 - using the command line <option 22.467 - role="hg-opt-log">--template</option> option.</para> 22.468 - 22.469 - <sect2> 22.470 - <title>The simplest of style files</title> 22.471 - 22.472 - <para id="x_5bd">Our simple style file contains just one line:</para> 22.473 - 22.474 - &interaction.template.simple.rev; 22.475 - 22.476 - <para id="x_5be">This tells Mercurial, <quote>if you're printing a 22.477 - changeset, use the text on the right as the 22.478 - template</quote>.</para> 22.479 - </sect2> 22.480 - 22.481 - <sect2> 22.482 - <title>Style file syntax</title> 22.483 - 22.484 - <para id="x_5bf">The syntax rules for a style file are simple.</para> 22.485 - 22.486 - <itemizedlist> 22.487 - <listitem><para id="x_5c0">The file is processed one line at a 22.488 - time.</para> 22.489 - </listitem> 22.490 - <listitem><para id="x_5c1">Leading and trailing white space are 22.491 - ignored.</para> 22.492 - </listitem> 22.493 - <listitem><para id="x_5c2">Empty lines are skipped.</para> 22.494 - </listitem> 22.495 - <listitem><para id="x_5c3">If a line starts with either of the characters 22.496 - <quote><literal>#</literal></quote> or 22.497 - <quote><literal>;</literal></quote>, the entire line is 22.498 - treated as a comment, and skipped as if empty.</para> 22.499 - </listitem> 22.500 - <listitem><para id="x_5c4">A line starts with a keyword. This must start 22.501 - with an alphabetic character or underscore, and can 22.502 - subsequently contain any alphanumeric character or 22.503 - underscore. (In regexp notation, a keyword must match 22.504 - <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para> 22.505 - </listitem> 22.506 - <listitem><para id="x_5c5">The next element must be an 22.507 - <quote><literal>=</literal></quote> character, which can 22.508 - be preceded or followed by an arbitrary amount of white 22.509 - space.</para> 22.510 - </listitem> 22.511 - <listitem><para id="x_5c6">If the rest of the line starts and ends with 22.512 - matching quote characters (either single or double quote), 22.513 - it is treated as a template body.</para> 22.514 - </listitem> 22.515 - <listitem><para id="x_5c7">If the rest of the line <emphasis>does 22.516 - not</emphasis> start with a quote character, it is 22.517 - treated as the name of a file; the contents of this file 22.518 - will be read and used as a template body.</para> 22.519 - </listitem></itemizedlist> 22.520 - </sect2> 22.521 - </sect1> 22.522 - 22.523 - <sect1> 22.524 - <title>Style files by example</title> 22.525 - 22.526 - <para id="x_5c8">To illustrate how to write a style file, we will construct a 22.527 - few by example. Rather than provide a complete style file and 22.528 - walk through it, we'll mirror the usual process of developing a 22.529 - style file by starting with something very simple, and walking 22.530 - through a series of successively more complete examples.</para> 22.531 - 22.532 - <sect2> 22.533 - <title>Identifying mistakes in style files</title> 22.534 - 22.535 - <para id="x_5c9">If Mercurial encounters a problem in a style file you are 22.536 - working on, it prints a terse error message that, once you 22.537 - figure out what it means, is actually quite useful.</para> 22.538 - 22.539 -&interaction.template.svnstyle.syntax.input; 22.540 - 22.541 - <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to 22.542 - define a <literal>changeset</literal> keyword, but forgets to 22.543 - give any content for it. When instructed to use this style 22.544 - file, Mercurial promptly complains.</para> 22.545 - 22.546 - &interaction.template.svnstyle.syntax.error; 22.547 - 22.548 - <para id="x_5cb">This error message looks intimidating, but it is not too 22.549 - hard to follow.</para> 22.550 - 22.551 - <itemizedlist> 22.552 - <listitem><para id="x_5cc">The first component is simply Mercurial's way 22.553 - of saying <quote>I am giving up</quote>.</para> 22.554 - <programlisting>___abort___: broken.style:1: parse error</programlisting> 22.555 - </listitem> 22.556 - <listitem><para id="x_5cd">Next comes the name of the style file that 22.557 - contains the error.</para> 22.558 - <programlisting>abort: ___broken.style___:1: parse error</programlisting> 22.559 - </listitem> 22.560 - <listitem><para id="x_5ce">Following the file name is the line number 22.561 - where the error was encountered.</para> 22.562 - <programlisting>abort: broken.style:___1___: parse error</programlisting> 22.563 - </listitem> 22.564 - <listitem><para id="x_5cf">Finally, a description of what went 22.565 - wrong.</para> 22.566 - <programlisting>abort: broken.style:1: ___parse error___</programlisting> 22.567 - </listitem> 22.568 - <listitem><para id="x_5d0">The description of the problem is not always 22.569 - clear (as in this case), but even when it is cryptic, it 22.570 - is almost always trivial to visually inspect the offending 22.571 - line in the style file and see what is wrong.</para> 22.572 - </listitem> 22.573 - </itemizedlist> 22.574 - </sect2> 22.575 - 22.576 - <sect2> 22.577 - <title>Uniquely identifying a repository</title> 22.578 - 22.579 - <para id="x_5d1">If you would like to be able to identify a Mercurial 22.580 - repository <quote>fairly uniquely</quote> using a short string 22.581 - as an identifier, you can use the first revision in the 22.582 - repository.</para> 22.583 - 22.584 - &interaction.template.svnstyle.id; 22.585 - 22.586 - <para id="x_5d2">This is likely to be unique, and so it is 22.587 - useful in many cases. There are a few caveats.</para> 22.588 - <itemizedlist> 22.589 - <listitem><para id="x_5d3">It will not work in a completely empty 22.590 - repository, because such a repository does not have a 22.591 - revision zero.</para> 22.592 - </listitem> 22.593 - <listitem><para id="x_5d4">Neither will it work in the (extremely rare) 22.594 - case where a repository is a merge of two or more formerly 22.595 - independent repositories, and you still have those 22.596 - repositories around.</para> 22.597 - </listitem></itemizedlist> 22.598 - <para id="x_5d5">Here are some uses to which you could put this 22.599 - identifier:</para> 22.600 - <itemizedlist> 22.601 - <listitem><para id="x_5d6">As a key into a table for a database that 22.602 - manages repositories on a server.</para> 22.603 - </listitem> 22.604 - <listitem><para id="x_5d7">As half of a {<emphasis>repository 22.605 - ID</emphasis>, <emphasis>revision ID</emphasis>} tuple. 22.606 - Save this information away when you run an automated build 22.607 - or other activity, so that you can <quote>replay</quote> 22.608 - the build later if necessary.</para> 22.609 - </listitem> 22.610 - </itemizedlist> 22.611 - </sect2> 22.612 - 22.613 - <sect2> 22.614 - <title>Listing files on multiple lines</title> 22.615 - 22.616 - <para id="x_714">Suppose we want to list the files changed by a changeset, 22.617 - one per line, with a little indentation before each file 22.618 - name.</para> 22.619 - 22.620 - &interaction.ch10-multiline.go; 22.621 - </sect2> 22.622 - 22.623 - <sect2> 22.624 - <title>Mimicking Subversion's output</title> 22.625 - 22.626 - <para id="x_5d8">Let's try to emulate the default output format used by 22.627 - another revision control tool, Subversion.</para> 22.628 - 22.629 - &interaction.template.svnstyle.short; 22.630 - 22.631 - <para id="x_5d9">Since Subversion's output style is fairly simple, it is 22.632 - easy to copy-and-paste a hunk of its output into a file, and 22.633 - replace the text produced above by Subversion with the 22.634 - template values we'd like to see expanded.</para> 22.635 - 22.636 - &interaction.template.svnstyle.template; 22.637 - 22.638 - <para id="x_5da">There are a few small ways in which this template deviates 22.639 - from the output produced by Subversion.</para> 22.640 - <itemizedlist> 22.641 - <listitem><para id="x_5db">Subversion prints a <quote>readable</quote> 22.642 - date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the 22.643 - example output above) in parentheses. Mercurial's 22.644 - templating engine does not provide a way to display a date 22.645 - in this format without also printing the time and time 22.646 - zone.</para> 22.647 - </listitem> 22.648 - <listitem><para id="x_5dc">We emulate Subversion's printing of 22.649 - <quote>separator</quote> lines full of 22.650 - <quote><literal>-</literal></quote> characters by ending 22.651 - the template with such a line. We use the templating 22.652 - engine's <literal role="template-keyword">header</literal> 22.653 - keyword to print a separator line as the first line of 22.654 - output (see below), thus achieving similar output to 22.655 - Subversion.</para> 22.656 - </listitem> 22.657 - <listitem><para id="x_5dd">Subversion's output includes a count in the 22.658 - header of the number of lines in the commit message. We 22.659 - cannot replicate this in Mercurial; the templating engine 22.660 - does not currently provide a filter that counts the number 22.661 - of lines the template generates.</para> 22.662 - </listitem></itemizedlist> 22.663 - <para id="x_5de">It took me no more than a minute or two of work to replace 22.664 - literal text from an example of Subversion's output with some 22.665 - keywords and filters to give the template above. The style 22.666 - file simply refers to the template.</para> 22.667 - 22.668 - &interaction.template.svnstyle.style; 22.669 - 22.670 - <para id="x_5df">We could have included the text of the template file 22.671 - directly in the style file by enclosing it in quotes and 22.672 - replacing the newlines with 22.673 - <quote><literal>\n</literal></quote> sequences, but it would 22.674 - have made the style file too difficult to read. Readability 22.675 - is a good guide when you're trying to decide whether some text 22.676 - belongs in a style file, or in a template file that the style 22.677 - file points to. If the style file will look too big or 22.678 - cluttered if you insert a literal piece of text, drop it into 22.679 - a template instead.</para> 22.680 - </sect2> 22.681 - </sect1> 22.682 -</chapter> 22.683 - 22.684 -<!-- 22.685 -local variables: 22.686 -sgml-parent-document: ("00book.xml" "book" "chapter") 22.687 -end: 22.688 --->
23.1 --- a/en/ch11-mq.xml Thu May 07 21:06:49 2009 -0700 23.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 23.3 @@ -1,1368 +0,0 @@ 23.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 23.5 - 23.6 -<chapter id="chap:mq"> 23.7 - <?dbhtml filename="managing-change-with-mercurial-queues.html"?> 23.8 - <title>Managing change with Mercurial Queues</title> 23.9 - 23.10 - <sect1 id="sec:mq:patch-mgmt"> 23.11 - <title>The patch management problem</title> 23.12 - 23.13 - <para id="x_3ac">Here is a common scenario: you need to install a software 23.14 - package from source, but you find a bug that you must fix in the 23.15 - source before you can start using the package. You make your 23.16 - changes, forget about the package for a while, and a few months 23.17 - later you need to upgrade to a newer version of the package. If 23.18 - the newer version of the package still has the bug, you must 23.19 - extract your fix from the older source tree and apply it against 23.20 - the newer version. This is a tedious task, and it's easy to 23.21 - make mistakes.</para> 23.22 - 23.23 - <para id="x_3ad">This is a simple case of the <quote>patch management</quote> 23.24 - problem. You have an <quote>upstream</quote> source tree that 23.25 - you can't change; you need to make some local changes on top of 23.26 - the upstream tree; and you'd like to be able to keep those 23.27 - changes separate, so that you can apply them to newer versions 23.28 - of the upstream source.</para> 23.29 - 23.30 - <para id="x_3ae">The patch management problem arises in many situations. 23.31 - Probably the most visible is that a user of an open source 23.32 - software project will contribute a bug fix or new feature to the 23.33 - project's maintainers in the form of a patch.</para> 23.34 - 23.35 - <para id="x_3af">Distributors of operating systems that include open source 23.36 - software often need to make changes to the packages they 23.37 - distribute so that they will build properly in their 23.38 - environments.</para> 23.39 - 23.40 - <para id="x_3b0">When you have few changes to maintain, it is easy to manage 23.41 - a single patch using the standard <command>diff</command> and 23.42 - <command>patch</command> programs (see <xref 23.43 - linkend="sec:mq:patch"/> for a discussion of these 23.44 - tools). Once the number of changes grows, it starts to make 23.45 - sense to maintain patches as discrete <quote>chunks of 23.46 - work,</quote> so that for example a single patch will contain 23.47 - only one bug fix (the patch might modify several files, but it's 23.48 - doing <quote>only one thing</quote>), and you may have a number 23.49 - of such patches for different bugs you need fixed and local 23.50 - changes you require. In this situation, if you submit a bug fix 23.51 - patch to the upstream maintainers of a package and they include 23.52 - your fix in a subsequent release, you can simply drop that 23.53 - single patch when you're updating to the newer release.</para> 23.54 - 23.55 - <para id="x_3b1">Maintaining a single patch against an upstream tree is a 23.56 - little tedious and error-prone, but not difficult. However, the 23.57 - complexity of the problem grows rapidly as the number of patches 23.58 - you have to maintain increases. With more than a tiny number of 23.59 - patches in hand, understanding which ones you have applied and 23.60 - maintaining them moves from messy to overwhelming.</para> 23.61 - 23.62 - <para id="x_3b2">Fortunately, Mercurial includes a powerful extension, 23.63 - Mercurial Queues (or simply <quote>MQ</quote>), that massively 23.64 - simplifies the patch management problem.</para> 23.65 - 23.66 - </sect1> 23.67 - <sect1 id="sec:mq:history"> 23.68 - <title>The prehistory of Mercurial Queues</title> 23.69 - 23.70 - <para id="x_3b3">During the late 1990s, several Linux kernel developers 23.71 - started to maintain <quote>patch series</quote> that modified 23.72 - the behavior of the Linux kernel. Some of these series were 23.73 - focused on stability, some on feature coverage, and others were 23.74 - more speculative.</para> 23.75 - 23.76 - <para id="x_3b4">The sizes of these patch series grew rapidly. In 2002, 23.77 - Andrew Morton published some shell scripts he had been using to 23.78 - automate the task of managing his patch queues. Andrew was 23.79 - successfully using these scripts to manage hundreds (sometimes 23.80 - thousands) of patches on top of the Linux kernel.</para> 23.81 - 23.82 - <sect2 id="sec:mq:quilt"> 23.83 - <title>A patchwork quilt</title> 23.84 - 23.85 - <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson 23.86 - borrowed the approach of Andrew's scripts and published a tool 23.87 - called <quote>patchwork quilt</quote> 23.88 - <citation>web:quilt</citation>, or simply <quote>quilt</quote> 23.89 - (see <citation>gruenbacher:2005</citation> for a paper 23.90 - describing it). Because quilt substantially automated patch 23.91 - management, it rapidly gained a large following among open 23.92 - source software developers.</para> 23.93 - 23.94 - <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on 23.95 - top of a directory tree. To begin, you tell quilt to manage a 23.96 - directory tree, and tell it which files you want to manage; it 23.97 - stores away the names and contents of those files. To fix a 23.98 - bug, you create a new patch (using a single command), edit the 23.99 - files you need to fix, then <quote>refresh</quote> the 23.100 - patch.</para> 23.101 - 23.102 - <para id="x_3b7">The refresh step causes quilt to scan the directory tree; 23.103 - it updates the patch with all of the changes you have made. 23.104 - You can create another patch on top of the first, which will 23.105 - track the changes required to modify the tree from <quote>tree 23.106 - with one patch applied</quote> to <quote>tree with two 23.107 - patches applied</quote>.</para> 23.108 - 23.109 - <para id="x_3b8">You can <emphasis>change</emphasis> which patches are 23.110 - applied to the tree. If you <quote>pop</quote> a patch, the 23.111 - changes made by that patch will vanish from the directory 23.112 - tree. Quilt remembers which patches you have popped, though, 23.113 - so you can <quote>push</quote> a popped patch again, and the 23.114 - directory tree will be restored to contain the modifications 23.115 - in the patch. Most importantly, you can run the 23.116 - <quote>refresh</quote> command at any time, and the topmost 23.117 - applied patch will be updated. This means that you can, at 23.118 - any time, change both which patches are applied and what 23.119 - modifications those patches make.</para> 23.120 - 23.121 - <para id="x_3b9">Quilt knows nothing about revision control tools, so it 23.122 - works equally well on top of an unpacked tarball or a 23.123 - Subversion working copy.</para> 23.124 - </sect2> 23.125 - 23.126 - <sect2 id="sec:mq:quilt-mq"> 23.127 - <title>From patchwork quilt to Mercurial Queues</title> 23.128 - 23.129 - <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and 23.130 - wrote an extension that he called Mercurial Queues, which 23.131 - added quilt-like behavior to Mercurial.</para> 23.132 - 23.133 - <para id="x_3bb">The key difference between quilt and MQ is that quilt 23.134 - knows nothing about revision control systems, while MQ is 23.135 - <emphasis>integrated</emphasis> into Mercurial. Each patch 23.136 - that you push is represented as a Mercurial changeset. Pop a 23.137 - patch, and the changeset goes away.</para> 23.138 - 23.139 - <para id="x_3bc">Because quilt does not care about revision control tools, 23.140 - it is still a tremendously useful piece of software to know 23.141 - about for situations where you cannot use Mercurial and 23.142 - MQ.</para> 23.143 - 23.144 - </sect2> 23.145 - </sect1> 23.146 - <sect1> 23.147 - <title>The huge advantage of MQ</title> 23.148 - 23.149 - <para id="x_3bd">I cannot overstate the value that MQ offers through the 23.150 - unification of patches and revision control.</para> 23.151 - 23.152 - <para id="x_3be">A major reason that patches have persisted in the free 23.153 - software and open source world&emdash;in spite of the 23.154 - availability of increasingly capable revision control tools over 23.155 - the years&emdash;is the <emphasis>agility</emphasis> they 23.156 - offer.</para> 23.157 - 23.158 - <para id="x_3bf">Traditional revision control tools make a permanent, 23.159 - irreversible record of everything that you do. While this has 23.160 - great value, it's also somewhat stifling. If you want to 23.161 - perform a wild-eyed experiment, you have to be careful in how 23.162 - you go about it, or you risk leaving unneeded&emdash;or worse, 23.163 - misleading or destabilising&emdash;traces of your missteps and 23.164 - errors in the permanent revision record.</para> 23.165 - 23.166 - <para id="x_3c0">By contrast, MQ's marriage of distributed revision control 23.167 - with patches makes it much easier to isolate your work. Your 23.168 - patches live on top of normal revision history, and you can make 23.169 - them disappear or reappear at will. If you don't like a patch, 23.170 - you can drop it. If a patch isn't quite as you want it to be, 23.171 - simply fix it&emdash;as many times as you need to, until you 23.172 - have refined it into the form you desire.</para> 23.173 - 23.174 - <para id="x_3c1">As an example, the integration of patches with revision 23.175 - control makes understanding patches and debugging their 23.176 - effects&emdash;and their interplay with the code they're based 23.177 - on&emdash;<emphasis>enormously</emphasis> easier. Since every 23.178 - applied patch has an associated changeset, you can give <command 23.179 - role="hg-cmd">hg log</command> a file name to see which 23.180 - changesets and patches affected the file. You can use the 23.181 - <command role="hg-cmd">hg bisect</command> command to 23.182 - binary-search through all changesets and applied patches to see 23.183 - where a bug got introduced or fixed. You can use the <command 23.184 - role="hg-cmd">hg annotate</command> command to see which 23.185 - changeset or patch modified a particular line of a source file. 23.186 - And so on.</para> 23.187 - </sect1> 23.188 - 23.189 - <sect1 id="sec:mq:patch"> 23.190 - <title>Understanding patches</title> 23.191 - 23.192 - <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is 23.193 - helpful to understand what patches are, and a little about the 23.194 - tools that work with them.</para> 23.195 - 23.196 - <para id="x_3c3">The traditional Unix <command>diff</command> command 23.197 - compares two files, and prints a list of differences between 23.198 - them. The <command>patch</command> command understands these 23.199 - differences as <emphasis>modifications</emphasis> to make to a 23.200 - file. Take a look below for a simple example of these commands 23.201 - in action.</para> 23.202 - 23.203 - &interaction.mq.dodiff.diff; 23.204 - 23.205 - <para id="x_3c4">The type of file that <command>diff</command> generates (and 23.206 - <command>patch</command> takes as input) is called a 23.207 - <quote>patch</quote> or a <quote>diff</quote>; there is no 23.208 - difference between a patch and a diff. (We'll use the term 23.209 - <quote>patch</quote>, since it's more commonly used.)</para> 23.210 - 23.211 - <para id="x_3c5">A patch file can start with arbitrary text; the 23.212 - <command>patch</command> command ignores this text, but MQ uses 23.213 - it as the commit message when creating changesets. To find the 23.214 - beginning of the patch content, <command>patch</command> 23.215 - searches for the first line that starts with the string 23.216 - <quote><literal>diff -</literal></quote>.</para> 23.217 - 23.218 - <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs 23.219 - (<command>patch</command> can accept several other diff formats, 23.220 - but MQ doesn't). A unified diff contains two kinds of header. 23.221 - The <emphasis>file header</emphasis> describes the file being 23.222 - modified; it contains the name of the file to modify. When 23.223 - <command>patch</command> sees a new file header, it looks for a 23.224 - file with that name to start modifying.</para> 23.225 - 23.226 - <para id="x_3c7">After the file header comes a series of 23.227 - <emphasis>hunks</emphasis>. Each hunk starts with a header; 23.228 - this identifies the range of line numbers within the file that 23.229 - the hunk should modify. Following the header, a hunk starts and 23.230 - ends with a few (usually three) lines of text from the 23.231 - unmodified file; these are called the 23.232 - <emphasis>context</emphasis> for the hunk. If there's only a 23.233 - small amount of context between successive hunks, 23.234 - <command>diff</command> doesn't print a new hunk header; it just 23.235 - runs the hunks together, with a few lines of context between 23.236 - modifications.</para> 23.237 - 23.238 - <para id="x_3c8">Each line of context begins with a space character. Within 23.239 - the hunk, a line that begins with 23.240 - <quote><literal>-</literal></quote> means <quote>remove this 23.241 - line,</quote> while a line that begins with 23.242 - <quote><literal>+</literal></quote> means <quote>insert this 23.243 - line.</quote> For example, a line that is modified is 23.244 - represented by one deletion and one insertion.</para> 23.245 - 23.246 - <para id="x_3c9">We will return to some of the more subtle aspects of patches 23.247 - later (in <xref linkend="sec:mq:adv-patch"/>), but you 23.248 - should have 23.249 - enough information now to use MQ.</para> 23.250 - </sect1> 23.251 - 23.252 - <sect1 id="sec:mq:start"> 23.253 - <title>Getting started with Mercurial Queues</title> 23.254 - 23.255 - <para id="x_3ca">Because MQ is implemented as an extension, you must 23.256 - explicitly enable before you can use it. (You don't need to 23.257 - download anything; MQ ships with the standard Mercurial 23.258 - distribution.) To enable MQ, edit your <filename 23.259 - role="home">~/.hgrc</filename> file, and add the lines 23.260 - below.</para> 23.261 - 23.262 - <programlisting>[extensions] 23.263 -hgext.mq =</programlisting> 23.264 - 23.265 - <para id="x_3cb">Once the extension is enabled, it will make a number of new 23.266 - commands available. To verify that the extension is working, 23.267 - you can use <command role="hg-cmd">hg help</command> to see if 23.268 - the <command role="hg-ext-mq">qinit</command> command is now 23.269 - available.</para> 23.270 - 23.271 - &interaction.mq.qinit-help.help; 23.272 - 23.273 - <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial 23.274 - repository, and its commands only operate within that 23.275 - repository. To get started, simply prepare the repository using 23.276 - the <command role="hg-ext-mq">qinit</command> command.</para> 23.277 - 23.278 - &interaction.mq.tutorial.qinit; 23.279 - 23.280 - <para id="x_3cd">This command creates an empty directory called <filename 23.281 - role="special" class="directory">.hg/patches</filename>, where 23.282 - MQ will keep its metadata. As with many Mercurial commands, the 23.283 - <command role="hg-ext-mq">qinit</command> command prints nothing 23.284 - if it succeeds.</para> 23.285 - 23.286 - <sect2> 23.287 - <title>Creating a new patch</title> 23.288 - 23.289 - <para id="x_3ce">To begin work on a new patch, use the <command 23.290 - role="hg-ext-mq">qnew</command> command. This command takes 23.291 - one argument, the name of the patch to create.</para> 23.292 - 23.293 - <para id="x_3cf">MQ will use this as the name of an actual file in the 23.294 - <filename role="special" 23.295 - class="directory">.hg/patches</filename> directory, as you 23.296 - can see below.</para> 23.297 - 23.298 - &interaction.mq.tutorial.qnew; 23.299 - 23.300 - <para id="x_3d0">Also newly present in the <filename role="special" 23.301 - class="directory">.hg/patches</filename> directory are two 23.302 - other files, <filename role="special">series</filename> and 23.303 - <filename role="special">status</filename>. The <filename 23.304 - role="special">series</filename> file lists all of the 23.305 - patches that MQ knows about for this repository, with one 23.306 - patch per line. Mercurial uses the <filename 23.307 - role="special">status</filename> file for internal 23.308 - book-keeping; it tracks all of the patches that MQ has 23.309 - <emphasis>applied</emphasis> in this repository.</para> 23.310 - 23.311 - <note> 23.312 - <para id="x_3d1"> You may sometimes want to edit the <filename 23.313 - role="special">series</filename> file by hand; for 23.314 - example, to change the sequence in which some patches are 23.315 - applied. However, manually editing the <filename 23.316 - role="special">status</filename> file is almost always a 23.317 - bad idea, as it's easy to corrupt MQ's idea of what is 23.318 - happening.</para> 23.319 - </note> 23.320 - 23.321 - <para id="x_3d2">Once you have created your new patch, you can edit files 23.322 - in the working directory as you usually would. All of the 23.323 - normal Mercurial commands, such as <command role="hg-cmd">hg 23.324 - diff</command> and <command role="hg-cmd">hg 23.325 - annotate</command>, work exactly as they did before.</para> 23.326 - </sect2> 23.327 - 23.328 - <sect2> 23.329 - <title>Refreshing a patch</title> 23.330 - 23.331 - <para id="x_3d3">When you reach a point where you want to save your work, 23.332 - use the <command role="hg-ext-mq">qrefresh</command> command 23.333 - to update the patch you are working on.</para> 23.334 - 23.335 - &interaction.mq.tutorial.qrefresh; 23.336 - 23.337 - <para id="x_3d4">This command folds the changes you have made in the 23.338 - working directory into your patch, and updates its 23.339 - corresponding changeset to contain those changes.</para> 23.340 - 23.341 - <para id="x_3d5">You can run <command role="hg-ext-mq">qrefresh</command> 23.342 - as often as you like, so it's a good way to 23.343 - <quote>checkpoint</quote> your work. Refresh your patch at an 23.344 - opportune time; try an experiment; and if the experiment 23.345 - doesn't work out, <command role="hg-cmd">hg revert</command> 23.346 - your modifications back to the last time you refreshed.</para> 23.347 - 23.348 - &interaction.mq.tutorial.qrefresh2; 23.349 - </sect2> 23.350 - 23.351 - <sect2> 23.352 - <title>Stacking and tracking patches</title> 23.353 - 23.354 - <para id="x_3d6">Once you have finished working on a patch, or need to work 23.355 - on another, you can use the <command 23.356 - role="hg-ext-mq">qnew</command> command again to create a 23.357 - new patch. Mercurial will apply this patch on top of your 23.358 - existing patch.</para> 23.359 - 23.360 - &interaction.mq.tutorial.qnew2; 23.361 - 23.362 - <para id="x_3d7">Notice that the patch contains the changes in our prior 23.363 - patch as part of its context (you can see this more clearly in 23.364 - the output of <command role="hg-cmd">hg 23.365 - annotate</command>).</para> 23.366 - 23.367 - <para id="x_3d8">So far, with the exception of <command 23.368 - role="hg-ext-mq">qnew</command> and <command 23.369 - role="hg-ext-mq">qrefresh</command>, we've been careful to 23.370 - only use regular Mercurial commands. However, MQ provides 23.371 - many commands that are easier to use when you are thinking 23.372 - about patches, as illustrated below.</para> 23.373 - 23.374 - &interaction.mq.tutorial.qseries; 23.375 - 23.376 - <itemizedlist> 23.377 - <listitem><para id="x_3d9">The <command 23.378 - role="hg-ext-mq">qseries</command> command lists every 23.379 - patch that MQ knows about in this repository, from oldest 23.380 - to newest (most recently 23.381 - <emphasis>created</emphasis>).</para> 23.382 - </listitem> 23.383 - <listitem><para id="x_3da">The <command 23.384 - role="hg-ext-mq">qapplied</command> command lists every 23.385 - patch that MQ has <emphasis>applied</emphasis> in this 23.386 - repository, again from oldest to newest (most recently 23.387 - applied).</para> 23.388 - </listitem></itemizedlist> 23.389 - </sect2> 23.390 - 23.391 - <sect2> 23.392 - <title>Manipulating the patch stack</title> 23.393 - 23.394 - <para id="x_3db">The previous discussion implied that there must be a 23.395 - difference between <quote>known</quote> and 23.396 - <quote>applied</quote> patches, and there is. MQ can manage a 23.397 - patch without it being applied in the repository.</para> 23.398 - 23.399 - <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding 23.400 - changeset in the repository, and the effects of the patch and 23.401 - changeset are visible in the working directory. You can undo 23.402 - the application of a patch using the <command 23.403 - role="hg-ext-mq">qpop</command> command. MQ still 23.404 - <emphasis>knows about</emphasis>, or manages, a popped patch, 23.405 - but the patch no longer has a corresponding changeset in the 23.406 - repository, and the working directory does not contain the 23.407 - changes made by the patch. <xref 23.408 - linkend="fig:mq:stack"/> illustrates 23.409 - the difference between applied and tracked patches.</para> 23.410 - 23.411 - <figure id="fig:mq:stack"> 23.412 - <title>Applied and unapplied patches in the MQ patch 23.413 - stack</title> 23.414 - <mediaobject> 23.415 - <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject> 23.416 - <textobject><phrase>XXX add text</phrase></textobject> 23.417 - </mediaobject> 23.418 - </figure> 23.419 - 23.420 - <para id="x_3de">You can reapply an unapplied, or popped, patch using the 23.421 - <command role="hg-ext-mq">qpush</command> command. This 23.422 - creates a new changeset to correspond to the patch, and the 23.423 - patch's changes once again become present in the working 23.424 - directory. See below for examples of <command 23.425 - role="hg-ext-mq">qpop</command> and <command 23.426 - role="hg-ext-mq">qpush</command> in action.</para> 23.427 - 23.428 - &interaction.mq.tutorial.qpop; 23.429 - 23.430 - <para id="x_3df">Notice that once we have popped a patch or two patches, 23.431 - the output of <command role="hg-ext-mq">qseries</command> 23.432 - remains the same, while that of <command 23.433 - role="hg-ext-mq">qapplied</command> has changed.</para> 23.434 - 23.435 - </sect2> 23.436 - 23.437 - <sect2> 23.438 - <title>Pushing and popping many patches</title> 23.439 - 23.440 - <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and 23.441 - <command role="hg-ext-mq">qpop</command> each operate on a 23.442 - single patch at a time by default, you can push and pop many 23.443 - patches in one go. The <option 23.444 - role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to 23.445 - <command role="hg-ext-mq">qpush</command> causes it to push 23.446 - all unapplied patches, while the <option 23.447 - role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command 23.448 - role="hg-ext-mq">qpop</command> causes it to pop all applied 23.449 - patches. (For some more ways to push and pop many patches, 23.450 - see <xref linkend="sec:mq:perf"/> below.)</para> 23.451 - 23.452 - &interaction.mq.tutorial.qpush-a; 23.453 - </sect2> 23.454 - 23.455 - <sect2> 23.456 - <title>Safety checks, and overriding them</title> 23.457 - 23.458 - <para id="x_3e1">Several MQ commands check the working directory before 23.459 - they do anything, and fail if they find any modifications. 23.460 - They do this to ensure that you won't lose any changes that 23.461 - you have made, but not yet incorporated into a patch. The 23.462 - example below illustrates this; the <command 23.463 - role="hg-ext-mq">qnew</command> command will not create a 23.464 - new patch if there are outstanding changes, caused in this 23.465 - case by the <command role="hg-cmd">hg add</command> of 23.466 - <filename>file3</filename>.</para> 23.467 - 23.468 - &interaction.mq.tutorial.add; 23.469 - 23.470 - <para id="x_3e2">Commands that check the working directory all take an 23.471 - <quote>I know what I'm doing</quote> option, which is always 23.472 - named <option>-f</option>. The exact meaning of 23.473 - <option>-f</option> depends on the command. For example, 23.474 - <command role="hg-cmd">hg qnew <option 23.475 - role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command> 23.476 - will incorporate any outstanding changes into the new patch it 23.477 - creates, but <command role="hg-cmd">hg qpop <option 23.478 - role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command> 23.479 - will revert modifications to any files affected by the patch 23.480 - that it is popping. Be sure to read the documentation for a 23.481 - command's <option>-f</option> option before you use it!</para> 23.482 - </sect2> 23.483 - 23.484 - <sect2> 23.485 - <title>Working on several patches at once</title> 23.486 - 23.487 - <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command 23.488 - always refreshes the <emphasis>topmost</emphasis> applied 23.489 - patch. This means that you can suspend work on one patch (by 23.490 - refreshing it), pop or push to make a different patch the top, 23.491 - and work on <emphasis>that</emphasis> patch for a 23.492 - while.</para> 23.493 - 23.494 - <para id="x_3e4">Here's an example that illustrates how you can use this 23.495 - ability. Let's say you're developing a new feature as two 23.496 - patches. The first is a change to the core of your software, 23.497 - and the second&emdash;layered on top of the 23.498 - first&emdash;changes the user interface to use the code you 23.499 - just added to the core. If you notice a bug in the core while 23.500 - you're working on the UI patch, it's easy to fix the core. 23.501 - Simply <command role="hg-ext-mq">qrefresh</command> the UI 23.502 - patch to save your in-progress changes, and <command 23.503 - role="hg-ext-mq">qpop</command> down to the core patch. Fix 23.504 - the core bug, <command role="hg-ext-mq">qrefresh</command> the 23.505 - core patch, and <command role="hg-ext-mq">qpush</command> back 23.506 - to the UI patch to continue where you left off.</para> 23.507 - </sect2> 23.508 - </sect1> 23.509 - 23.510 - <sect1 id="sec:mq:adv-patch"> 23.511 - <title>More about patches</title> 23.512 - 23.513 - <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply 23.514 - patches, so it's helpful to know a few more detailed aspects of 23.515 - how <command>patch</command> works, and about patches 23.516 - themselves.</para> 23.517 - 23.518 - <sect2> 23.519 - <title>The strip count</title> 23.520 - 23.521 - <para id="x_3e6">If you look at the file headers in a patch, you will 23.522 - notice that the pathnames usually have an extra component on 23.523 - the front that isn't present in the actual path name. This is 23.524 - a holdover from the way that people used to generate patches 23.525 - (people still do this, but it's somewhat rare with modern 23.526 - revision control tools).</para> 23.527 - 23.528 - <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide 23.529 - that she wanted to create a patch. So she'd rename her 23.530 - working directory, unpack the tarball again (hence the need 23.531 - for the rename), and use the <option 23.532 - role="cmd-opt-diff">-r</option> and <option 23.533 - role="cmd-opt-diff">-N</option> options to 23.534 - <command>diff</command> to recursively generate a patch 23.535 - between the unmodified directory and the modified one. The 23.536 - result would be that the name of the unmodified directory 23.537 - would be at the front of the left-hand path in every file 23.538 - header, and the name of the modified directory would be at the 23.539 - front of the right-hand path.</para> 23.540 - 23.541 - <para id="x_3e8">Since someone receiving a patch from the Alices of the net 23.542 - would be unlikely to have unmodified and modified directories 23.543 - with exactly the same names, the <command>patch</command> 23.544 - command has a <option role="cmd-opt-patch">-p</option> option 23.545 - that indicates the number of leading path name components to 23.546 - strip when trying to apply a patch. This number is called the 23.547 - <emphasis>strip count</emphasis>.</para> 23.548 - 23.549 - <para id="x_3e9">An option of <quote><literal>-p1</literal></quote> means 23.550 - <quote>use a strip count of one</quote>. If 23.551 - <command>patch</command> sees a file name 23.552 - <filename>foo/bar/baz</filename> in a file header, it will 23.553 - strip <filename>foo</filename> and try to patch a file named 23.554 - <filename>bar/baz</filename>. (Strictly speaking, the strip 23.555 - count refers to the number of <emphasis>path 23.556 - separators</emphasis> (and the components that go with them 23.557 - ) to strip. A strip count of one will turn 23.558 - <filename>foo/bar</filename> into <filename>bar</filename>, 23.559 - but <filename>/foo/bar</filename> (notice the extra leading 23.560 - slash) into <filename>foo/bar</filename>.)</para> 23.561 - 23.562 - <para id="x_3ea">The <quote>standard</quote> strip count for patches is 23.563 - one; almost all patches contain one leading path name 23.564 - component that needs to be stripped. Mercurial's <command 23.565 - role="hg-cmd">hg diff</command> command generates path names 23.566 - in this form, and the <command role="hg-cmd">hg 23.567 - import</command> command and MQ expect patches to have a 23.568 - strip count of one.</para> 23.569 - 23.570 - <para id="x_3eb">If you receive a patch from someone that you want to add 23.571 - to your patch queue, and the patch needs a strip count other 23.572 - than one, you cannot just <command 23.573 - role="hg-ext-mq">qimport</command> the patch, because 23.574 - <command role="hg-ext-mq">qimport</command> does not yet have 23.575 - a <literal>-p</literal> option (see <ulink role="hg-bug" 23.576 - url="http://www.selenic.com/mercurial/bts/issue311">issue 23.577 - 311</ulink>). Your best bet is to <command 23.578 - role="hg-ext-mq">qnew</command> a patch of your own, then 23.579 - use <command>patch -pN</command> to apply their patch, 23.580 - followed by <command role="hg-cmd">hg addremove</command> to 23.581 - pick up any files added or removed by the patch, followed by 23.582 - <command role="hg-ext-mq">hg qrefresh</command>. This 23.583 - complexity may become unnecessary; see <ulink role="hg-bug" 23.584 - url="http://www.selenic.com/mercurial/bts/issue311">issue 23.585 - 311</ulink> for details. 23.586 - </para> 23.587 - </sect2> 23.588 - 23.589 - <sect2> 23.590 - <title>Strategies for applying a patch</title> 23.591 - 23.592 - <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a 23.593 - handful of successively less accurate strategies to try to 23.594 - make the hunk apply. This falling-back technique often makes 23.595 - it possible to take a patch that was generated against an old 23.596 - version of a file, and apply it against a newer version of 23.597 - that file.</para> 23.598 - 23.599 - <para id="x_3ed">First, <command>patch</command> tries an exact match, 23.600 - where the line numbers, the context, and the text to be 23.601 - modified must apply exactly. If it cannot make an exact 23.602 - match, it tries to find an exact match for the context, 23.603 - without honouring the line numbering information. If this 23.604 - succeeds, it prints a line of output saying that the hunk was 23.605 - applied, but at some <emphasis>offset</emphasis> from the 23.606 - original line number.</para> 23.607 - 23.608 - <para id="x_3ee">If a context-only match fails, <command>patch</command> 23.609 - removes the first and last lines of the context, and tries a 23.610 - <emphasis>reduced</emphasis> context-only match. If the hunk 23.611 - with reduced context succeeds, it prints a message saying that 23.612 - it applied the hunk with a <emphasis>fuzz factor</emphasis> 23.613 - (the number after the fuzz factor indicates how many lines of 23.614 - context <command>patch</command> had to trim before the patch 23.615 - applied).</para> 23.616 - 23.617 - <para id="x_3ef">When neither of these techniques works, 23.618 - <command>patch</command> prints a message saying that the hunk 23.619 - in question was rejected. It saves rejected hunks (also 23.620 - simply called <quote>rejects</quote>) to a file with the same 23.621 - name, and an added <filename role="special">.rej</filename> 23.622 - extension. It also saves an unmodified copy of the file with 23.623 - a <filename role="special">.orig</filename> extension; the 23.624 - copy of the file without any extensions will contain any 23.625 - changes made by hunks that <emphasis>did</emphasis> apply 23.626 - cleanly. If you have a patch that modifies 23.627 - <filename>foo</filename> with six hunks, and one of them fails 23.628 - to apply, you will have: an unmodified 23.629 - <filename>foo.orig</filename>, a <filename>foo.rej</filename> 23.630 - containing one hunk, and <filename>foo</filename>, containing 23.631 - the changes made by the five successful hunks.</para> 23.632 - </sect2> 23.633 - 23.634 - <sect2> 23.635 - <title>Some quirks of patch representation</title> 23.636 - 23.637 - <para id="x_3f0">There are a few useful things to know about how 23.638 - <command>patch</command> works with files.</para> 23.639 - <itemizedlist> 23.640 - <listitem><para id="x_3f1">This should already be obvious, but 23.641 - <command>patch</command> cannot handle binary 23.642 - files.</para> 23.643 - </listitem> 23.644 - <listitem><para id="x_3f2">Neither does it care about the executable bit; 23.645 - it creates new files as readable, but not 23.646 - executable.</para> 23.647 - </listitem> 23.648 - <listitem><para id="x_3f3"><command>patch</command> treats the removal of 23.649 - a file as a diff between the file to be removed and the 23.650 - empty file. So your idea of <quote>I deleted this 23.651 - file</quote> looks like <quote>every line of this file 23.652 - was deleted</quote> in a patch.</para> 23.653 - </listitem> 23.654 - <listitem><para id="x_3f4">It treats the addition of a file as a diff 23.655 - between the empty file and the file to be added. So in a 23.656 - patch, your idea of <quote>I added this file</quote> looks 23.657 - like <quote>every line of this file was 23.658 - added</quote>.</para> 23.659 - </listitem> 23.660 - <listitem><para id="x_3f5">It treats a renamed file as the removal of the 23.661 - old name, and the addition of the new name. This means 23.662 - that renamed files have a big footprint in patches. (Note 23.663 - also that Mercurial does not currently try to infer when 23.664 - files have been renamed or copied in a patch.)</para> 23.665 - </listitem> 23.666 - <listitem><para id="x_3f6"><command>patch</command> cannot represent 23.667 - empty files, so you cannot use a patch to represent the 23.668 - notion <quote>I added this empty file to the 23.669 - tree</quote>.</para> 23.670 - </listitem></itemizedlist> 23.671 - </sect2> 23.672 - 23.673 - <sect2> 23.674 - <title>Beware the fuzz</title> 23.675 - 23.676 - <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor, 23.677 - will often be completely successful, these inexact techniques 23.678 - naturally leave open the possibility of corrupting the patched 23.679 - file. The most common cases typically involve applying a 23.680 - patch twice, or at an incorrect location in the file. If 23.681 - <command>patch</command> or <command 23.682 - role="hg-ext-mq">qpush</command> ever mentions an offset or 23.683 - fuzz factor, you should make sure that the modified files are 23.684 - correct afterwards.</para> 23.685 - 23.686 - <para id="x_3f8">It's often a good idea to refresh a patch that has applied 23.687 - with an offset or fuzz factor; refreshing the patch generates 23.688 - new context information that will make it apply cleanly. I 23.689 - say <quote>often,</quote> not <quote>always,</quote> because 23.690 - sometimes refreshing a patch will make it fail to apply 23.691 - against a different revision of the underlying files. In some 23.692 - cases, such as when you're maintaining a patch that must sit 23.693 - on top of multiple versions of a source tree, it's acceptable 23.694 - to have a patch apply with some fuzz, provided you've verified 23.695 - the results of the patching process in such cases.</para> 23.696 - </sect2> 23.697 - 23.698 - <sect2> 23.699 - <title>Handling rejection</title> 23.700 - 23.701 - <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to 23.702 - apply a patch, it will print an error message and exit. If it 23.703 - has left <filename role="special">.rej</filename> files 23.704 - behind, it is usually best to fix up the rejected hunks before 23.705 - you push more patches or do any further work.</para> 23.706 - 23.707 - <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly, 23.708 - and no longer does because you've changed the underlying code 23.709 - that your patches are based on, Mercurial Queues can help; see 23.710 - <xref linkend="sec:mq:merge"/> for details.</para> 23.711 - 23.712 - <para id="x_3fb">Unfortunately, there aren't any great techniques for 23.713 - dealing with rejected hunks. Most often, you'll need to view 23.714 - the <filename role="special">.rej</filename> file and edit the 23.715 - target file, applying the rejected hunks by hand.</para> 23.716 - 23.717 - <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author 23.718 - of Mercurial Queues), wrote a tool called 23.719 - <command>mpatch</command> (<ulink 23.720 - url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 23.721 - which takes a simple approach to automating the application of 23.722 - hunks rejected by <command>patch</command>. The 23.723 - <command>mpatch</command> command can help with four common 23.724 - reasons that a hunk may be rejected:</para> 23.725 - 23.726 - <itemizedlist> 23.727 - <listitem><para id="x_3fe">The context in the middle of a hunk has 23.728 - changed.</para> 23.729 - </listitem> 23.730 - <listitem><para id="x_3ff">A hunk is missing some context at the 23.731 - beginning or end.</para> 23.732 - </listitem> 23.733 - <listitem><para id="x_400">A large hunk might apply better&emdash;either 23.734 - entirely or in part&emdash;if it was broken up into 23.735 - smaller hunks.</para> 23.736 - </listitem> 23.737 - <listitem><para id="x_401">A hunk removes lines with slightly different 23.738 - content than those currently present in the file.</para> 23.739 - </listitem></itemizedlist> 23.740 - 23.741 - <para id="x_402">If you use <command>mpatch</command>, you 23.742 - should be doubly careful to check your results when you're 23.743 - done. In fact, <command>mpatch</command> enforces this method 23.744 - of double-checking the tool's output, by automatically 23.745 - dropping you into a merge program when it has done its job, so 23.746 - that you can verify its work and finish off any remaining 23.747 - merges.</para> 23.748 - </sect2> 23.749 - </sect1> 23.750 - 23.751 - <sect1> 23.752 - <title>More on patch management</title> 23.753 - 23.754 - <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting 23.755 - to perform other kinds of patch management operations.</para> 23.756 - 23.757 - <sect2> 23.758 - <title>Deleting unwanted patches</title> 23.759 - 23.760 - <para id="x_6dc">If you want to get rid of a patch, use the <command 23.761 - role="hg-ext-mq">hg qdelete</command> command to delete the 23.762 - patch file and remove its entry from the patch series. If you 23.763 - try to delete a patch that is still applied, <command 23.764 - role="hg-ext-mq">hg qdelete</command> will refuse.</para> 23.765 - 23.766 - &interaction.ch11-qdelete.go; 23.767 - </sect2> 23.768 - 23.769 - <sect2> 23.770 - <title>Converting to and from permanent revisions</title> 23.771 - 23.772 - <para id="x_6dd">Once you're done working on a patch and want to 23.773 - turn it into a permanent changeset, use the <command 23.774 - role="hg-ext-mq">hg qfinish</command> command. Pass a revision 23.775 - to the command to identify the patch that you want to turn into 23.776 - a regular changeset; this patch must already be applied.</para> 23.777 - 23.778 - &interaction.ch11-qdelete.convert; 23.779 - 23.780 - <para id="x_6e0">The <command role="hg-ext-mq">hg qfinish</command> command 23.781 - accepts an <option>--all</option> or <option>-a</option> 23.782 - option, which turns all applied patches into regular 23.783 - changesets.</para> 23.784 - 23.785 - <para id="x_6de">It is also possible to turn an existing changeset into a 23.786 - patch, by passing the <option>-r</option> option to <command 23.787 - role="hg-ext-mq">hg qimport</command>.</para> 23.788 - 23.789 - &interaction.ch11-qdelete.import; 23.790 - 23.791 - <para id="x_6df">Note that it only makes sense to convert a changeset into 23.792 - a patch if you have not propagated that changeset into any 23.793 - other repositories. The imported changeset's ID will change 23.794 - every time you refresh the patch, which will make Mercurial 23.795 - treat it as unrelated to the original changeset if you have 23.796 - pushed it somewhere else.</para> 23.797 - </sect2> 23.798 - </sect1> 23.799 - 23.800 - <sect1 id="sec:mq:perf"> 23.801 - <title>Getting the best performance out of MQ</title> 23.802 - 23.803 - <para id="x_403">MQ is very efficient at handling a large number 23.804 - of patches. I ran some performance experiments in mid-2006 for a 23.805 - talk that I gave at the 2006 EuroPython conference (on modern 23.806 - hardware, you should expect better performance than you'll see 23.807 - below). I used as my data set the Linux 2.6.17-mm1 patch 23.808 - series, which consists of 1,738 patches. I applied these on top 23.809 - of a Linux kernel repository containing all 27,472 revisions 23.810 - between Linux 2.6.12-rc2 and Linux 2.6.17.</para> 23.811 - 23.812 - <para id="x_404">On my old, slow laptop, I was able to <command 23.813 - role="hg-cmd">hg qpush <option 23.814 - role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all 23.815 - 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop 23.816 - <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> 23.817 - them all in 30 seconds. (On a newer laptop, the time to push 23.818 - all patches dropped to two minutes.) I could <command 23.819 - role="hg-ext-mq">qrefresh</command> one of the biggest patches 23.820 - (which made 22,779 lines of changes to 287 files) in 6.6 23.821 - seconds.</para> 23.822 - 23.823 - <para id="x_405">Clearly, MQ is well suited to working in large trees, but 23.824 - there are a few tricks you can use to get the best performance 23.825 - of it.</para> 23.826 - 23.827 - <para id="x_406">First of all, try to <quote>batch</quote> operations 23.828 - together. Every time you run <command 23.829 - role="hg-ext-mq">qpush</command> or <command 23.830 - role="hg-ext-mq">qpop</command>, these commands scan the 23.831 - working directory once to make sure you haven't made some 23.832 - changes and then forgotten to run <command 23.833 - role="hg-ext-mq">qrefresh</command>. On a small tree, the 23.834 - time that this scan takes is unnoticeable. However, on a 23.835 - medium-sized tree (containing tens of thousands of files), it 23.836 - can take a second or more.</para> 23.837 - 23.838 - <para id="x_407">The <command role="hg-ext-mq">qpush</command> and <command 23.839 - role="hg-ext-mq">qpop</command> commands allow you to push and 23.840 - pop multiple patches at a time. You can identify the 23.841 - <quote>destination patch</quote> that you want to end up at. 23.842 - When you <command role="hg-ext-mq">qpush</command> with a 23.843 - destination specified, it will push patches until that patch is 23.844 - at the top of the applied stack. When you <command 23.845 - role="hg-ext-mq">qpop</command> to a destination, MQ will pop 23.846 - patches until the destination patch is at the top.</para> 23.847 - 23.848 - <para id="x_408">You can identify a destination patch using either the name 23.849 - of the patch, or by number. If you use numeric addressing, 23.850 - patches are counted from zero; this means that the first patch 23.851 - is zero, the second is one, and so on.</para> 23.852 - </sect1> 23.853 - 23.854 - <sect1 id="sec:mq:merge"> 23.855 - <title>Updating your patches when the underlying code 23.856 - changes</title> 23.857 - 23.858 - <para id="x_409">It's common to have a stack of patches on top of an 23.859 - underlying repository that you don't modify directly. If you're 23.860 - working on changes to third-party code, or on a feature that is 23.861 - taking longer to develop than the rate of change of the code 23.862 - beneath, you will often need to sync up with the underlying 23.863 - code, and fix up any hunks in your patches that no longer apply. 23.864 - This is called <emphasis>rebasing</emphasis> your patch 23.865 - series.</para> 23.866 - 23.867 - <para id="x_40a">The simplest way to do this is to <command role="hg-cmd">hg 23.868 - qpop <option role="hg-ext-mq-cmd-qpop-opt">hg 23.869 - -a</option></command> your patches, then <command 23.870 - role="hg-cmd">hg pull</command> changes into the underlying 23.871 - repository, and finally <command role="hg-cmd">hg qpush <option 23.872 - role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your 23.873 - patches again. MQ will stop pushing any time it runs across a 23.874 - patch that fails to apply during conflicts, allowing you to fix 23.875 - your conflicts, <command role="hg-ext-mq">qrefresh</command> the 23.876 - affected patch, and continue pushing until you have fixed your 23.877 - entire stack.</para> 23.878 - 23.879 - <para id="x_40b">This approach is easy to use and works well if you don't 23.880 - expect changes to the underlying code to affect how well your 23.881 - patches apply. If your patch stack touches code that is modified 23.882 - frequently or invasively in the underlying repository, however, 23.883 - fixing up rejected hunks by hand quickly becomes 23.884 - tiresome.</para> 23.885 - 23.886 - <para id="x_40c">It's possible to partially automate the rebasing process. 23.887 - If your patches apply cleanly against some revision of the 23.888 - underlying repo, MQ can use this information to help you to 23.889 - resolve conflicts between your patches and a different 23.890 - revision.</para> 23.891 - 23.892 - <para id="x_40d">The process is a little involved.</para> 23.893 - <orderedlist> 23.894 - <listitem><para id="x_40e">To begin, <command role="hg-cmd">hg qpush 23.895 - -a</command> all of your patches on top of the revision 23.896 - where you know that they apply cleanly.</para> 23.897 - </listitem> 23.898 - <listitem><para id="x_40f">Save a backup copy of your patch directory using 23.899 - <command role="hg-cmd">hg qsave <option 23.900 - role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option 23.901 - role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>. 23.902 - This prints the name of the directory that it has saved the 23.903 - patches in. It will save the patches to a directory called 23.904 - <filename role="special" 23.905 - class="directory">.hg/patches.N</filename>, where 23.906 - <literal>N</literal> is a small integer. It also commits a 23.907 - <quote>save changeset</quote> on top of your applied 23.908 - patches; this is for internal book-keeping, and records the 23.909 - states of the <filename role="special">series</filename> and 23.910 - <filename role="special">status</filename> files.</para> 23.911 - </listitem> 23.912 - <listitem><para id="x_410">Use <command role="hg-cmd">hg pull</command> to 23.913 - bring new changes into the underlying repository. (Don't 23.914 - run <command role="hg-cmd">hg pull -u</command>; see below 23.915 - for why.)</para> 23.916 - </listitem> 23.917 - <listitem><para id="x_411">Update to the new tip revision, using <command 23.918 - role="hg-cmd">hg update <option 23.919 - role="hg-opt-update">-C</option></command> to override 23.920 - the patches you have pushed.</para> 23.921 - </listitem> 23.922 - <listitem><para id="x_412">Merge all patches using <command>hg qpush -m 23.923 - -a</command>. The <option 23.924 - role="hg-ext-mq-cmd-qpush-opt">-m</option> option to 23.925 - <command role="hg-ext-mq">qpush</command> tells MQ to 23.926 - perform a three-way merge if the patch fails to 23.927 - apply.</para> 23.928 - </listitem></orderedlist> 23.929 - 23.930 - <para id="x_413">During the <command role="hg-cmd">hg qpush <option 23.931 - role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>, 23.932 - each patch in the <filename role="special">series</filename> 23.933 - file is applied normally. If a patch applies with fuzz or 23.934 - rejects, MQ looks at the queue you <command 23.935 - role="hg-ext-mq">qsave</command>d, and performs a three-way 23.936 - merge with the corresponding changeset. This merge uses 23.937 - Mercurial's normal merge machinery, so it may pop up a GUI merge 23.938 - tool to help you to resolve problems.</para> 23.939 - 23.940 - <para id="x_414">When you finish resolving the effects of a patch, MQ 23.941 - refreshes your patch based on the result of the merge.</para> 23.942 - 23.943 - <para id="x_415">At the end of this process, your repository will have one 23.944 - extra head from the old patch queue, and a copy of the old patch 23.945 - queue will be in <filename role="special" 23.946 - class="directory">.hg/patches.N</filename>. You can remove the 23.947 - extra head using <command role="hg-cmd">hg qpop -a -n 23.948 - patches.N</command> or <command role="hg-cmd">hg 23.949 - strip</command>. You can delete <filename role="special" 23.950 - class="directory">.hg/patches.N</filename> once you are sure 23.951 - that you no longer need it as a backup.</para> 23.952 - </sect1> 23.953 - 23.954 - <sect1> 23.955 - <title>Identifying patches</title> 23.956 - 23.957 - <para id="x_416">MQ commands that work with patches let you refer to a patch 23.958 - either by using its name or by a number. By name is obvious 23.959 - enough; pass the name <filename>foo.patch</filename> to <command 23.960 - role="hg-ext-mq">qpush</command>, for example, and it will 23.961 - push patches until <filename>foo.patch</filename> is 23.962 - applied.</para> 23.963 - 23.964 - <para id="x_417">As a shortcut, you can refer to a patch using both a name 23.965 - and a numeric offset; <literal>foo.patch-2</literal> means 23.966 - <quote>two patches before <literal>foo.patch</literal></quote>, 23.967 - while <literal>bar.patch+4</literal> means <quote>four patches 23.968 - after <literal>bar.patch</literal></quote>.</para> 23.969 - 23.970 - <para id="x_418">Referring to a patch by index isn't much different. The 23.971 - first patch printed in the output of <command 23.972 - role="hg-ext-mq">qseries</command> is patch zero (yes, it's 23.973 - one of those start-at-zero counting systems); the second is 23.974 - patch one; and so on.</para> 23.975 - 23.976 - <para id="x_419">MQ also makes it easy to work with patches when you are 23.977 - using normal Mercurial commands. Every command that accepts a 23.978 - changeset ID will also accept the name of an applied patch. MQ 23.979 - augments the tags normally in the repository with an eponymous 23.980 - one for each applied patch. In addition, the special tags 23.981 - <literal role="tag">qbase</literal> and 23.982 - <literal role="tag">qtip</literal> identify 23.983 - the <quote>bottom-most</quote> and topmost applied patches, 23.984 - respectively.</para> 23.985 - 23.986 - <para id="x_41a">These additions to Mercurial's normal tagging capabilities 23.987 - make dealing with patches even more of a breeze.</para> 23.988 - <itemizedlist> 23.989 - <listitem><para id="x_41b">Want to patchbomb a mailing list with your 23.990 - latest series of changes?</para> 23.991 - <programlisting>hg email qbase:qtip</programlisting> 23.992 - <para id="x_41c"> (Don't know what <quote>patchbombing</quote> is? See 23.993 - <xref linkend="sec:hgext:patchbomb"/>.)</para> 23.994 - </listitem> 23.995 - <listitem><para id="x_41d">Need to see all of the patches since 23.996 - <literal>foo.patch</literal> that have touched files in a 23.997 - subdirectory of your tree?</para> 23.998 - <programlisting>hg log -r foo.patch:qtip subdir</programlisting> 23.999 - </listitem> 23.1000 - </itemizedlist> 23.1001 - 23.1002 - <para id="x_41e">Because MQ makes the names of patches available to the rest 23.1003 - of Mercurial through its normal internal tag machinery, you 23.1004 - don't need to type in the entire name of a patch when you want 23.1005 - to identify it by name.</para> 23.1006 - 23.1007 - <para id="x_41f">Another nice consequence of representing patch names as tags 23.1008 - is that when you run the <command role="hg-cmd">hg log</command> 23.1009 - command, it will display a patch's name as a tag, simply as part 23.1010 - of its normal output. This makes it easy to visually 23.1011 - distinguish applied patches from underlying 23.1012 - <quote>normal</quote> revisions. The following example shows a 23.1013 - few normal Mercurial commands in use with applied 23.1014 - patches.</para> 23.1015 - 23.1016 - &interaction.mq.id.output; 23.1017 - </sect1> 23.1018 - 23.1019 - <sect1> 23.1020 - <title>Useful things to know about</title> 23.1021 - 23.1022 - <para id="x_420">There are a number of aspects of MQ usage that don't fit 23.1023 - tidily into sections of their own, but that are good to know. 23.1024 - Here they are, in one place.</para> 23.1025 - 23.1026 - <itemizedlist> 23.1027 - <listitem><para id="x_421">Normally, when you <command 23.1028 - role="hg-ext-mq">qpop</command> a patch and <command 23.1029 - role="hg-ext-mq">qpush</command> it again, the changeset 23.1030 - that represents the patch after the pop/push will have a 23.1031 - <emphasis>different identity</emphasis> than the changeset 23.1032 - that represented the hash beforehand. See <xref 23.1033 - linkend="sec:mqref:cmd:qpush"/> for 23.1034 - information as to why this is.</para> 23.1035 - </listitem> 23.1036 - <listitem><para id="x_422">It's not a good idea to <command 23.1037 - role="hg-cmd">hg merge</command> changes from another 23.1038 - branch with a patch changeset, at least if you want to 23.1039 - maintain the <quote>patchiness</quote> of that changeset and 23.1040 - changesets below it on the patch stack. If you try to do 23.1041 - this, it will appear to succeed, but MQ will become 23.1042 - confused.</para> 23.1043 - </listitem></itemizedlist> 23.1044 - </sect1> 23.1045 - 23.1046 - <sect1 id="sec:mq:repo"> 23.1047 - <title>Managing patches in a repository</title> 23.1048 - 23.1049 - <para id="x_423">Because MQ's <filename role="special" 23.1050 - class="directory">.hg/patches</filename> directory resides 23.1051 - outside a Mercurial repository's working directory, the 23.1052 - <quote>underlying</quote> Mercurial repository knows nothing 23.1053 - about the management or presence of patches.</para> 23.1054 - 23.1055 - <para id="x_424">This presents the interesting possibility of managing the 23.1056 - contents of the patch directory as a Mercurial repository in its 23.1057 - own right. This can be a useful way to work. For example, you 23.1058 - can work on a patch for a while, <command 23.1059 - role="hg-ext-mq">qrefresh</command> it, then <command 23.1060 - role="hg-cmd">hg commit</command> the current state of the 23.1061 - patch. This lets you <quote>roll back</quote> to that version 23.1062 - of the patch later on.</para> 23.1063 - 23.1064 - <para id="x_425">You can then share different versions of the same patch 23.1065 - stack among multiple underlying repositories. I use this when I 23.1066 - am developing a Linux kernel feature. I have a pristine copy of 23.1067 - my kernel sources for each of several CPU architectures, and a 23.1068 - cloned repository under each that contains the patches I am 23.1069 - working on. When I want to test a change on a different 23.1070 - architecture, I push my current patches to the patch repository 23.1071 - associated with that kernel tree, pop and push all of my 23.1072 - patches, and build and test that kernel.</para> 23.1073 - 23.1074 - <para id="x_426">Managing patches in a repository makes it possible for 23.1075 - multiple developers to work on the same patch series without 23.1076 - colliding with each other, all on top of an underlying source 23.1077 - base that they may or may not control.</para> 23.1078 - 23.1079 - <sect2> 23.1080 - <title>MQ support for patch repositories</title> 23.1081 - 23.1082 - <para id="x_427">MQ helps you to work with the <filename role="special" 23.1083 - class="directory">.hg/patches</filename> directory as a 23.1084 - repository; when you prepare a repository for working with 23.1085 - patches using <command role="hg-ext-mq">qinit</command>, you 23.1086 - can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg 23.1087 - -c</option> option to create the <filename role="special" 23.1088 - class="directory">.hg/patches</filename> directory as a 23.1089 - Mercurial repository.</para> 23.1090 - 23.1091 - <note> 23.1092 - <para id="x_428"> If you forget to use the <option 23.1093 - role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you 23.1094 - can simply go into the <filename role="special" 23.1095 - class="directory">.hg/patches</filename> directory at any 23.1096 - time and run <command role="hg-cmd">hg init</command>. 23.1097 - Don't forget to add an entry for the <filename 23.1098 - role="special">status</filename> file to the <filename 23.1099 - role="special">.hgignore</filename> file, though</para> 23.1100 - 23.1101 - <para id="x_429"> (<command role="hg-cmd">hg qinit <option 23.1102 - role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command> 23.1103 - does this for you automatically); you 23.1104 - <emphasis>really</emphasis> don't want to manage the 23.1105 - <filename role="special">status</filename> file.</para> 23.1106 - </note> 23.1107 - 23.1108 - <para id="x_42a">As a convenience, if MQ notices that the <filename 23.1109 - class="directory">.hg/patches</filename> directory is a 23.1110 - repository, it will automatically <command role="hg-cmd">hg 23.1111 - add</command> every patch that you create and import.</para> 23.1112 - 23.1113 - <para id="x_42b">MQ provides a shortcut command, <command 23.1114 - role="hg-ext-mq">qcommit</command>, that runs <command 23.1115 - role="hg-cmd">hg commit</command> in the <filename 23.1116 - role="special" class="directory">.hg/patches</filename> 23.1117 - directory. This saves some bothersome typing.</para> 23.1118 - 23.1119 - <para id="x_42c">Finally, as a convenience to manage the patch directory, 23.1120 - you can define the alias <command>mq</command> on Unix 23.1121 - systems. For example, on Linux systems using the 23.1122 - <command>bash</command> shell, you can include the following 23.1123 - snippet in your <filename 23.1124 - role="home">~/.bashrc</filename>.</para> 23.1125 - 23.1126 - <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting> 23.1127 - 23.1128 - <para id="x_42d">You can then issue commands of the form <command>mq 23.1129 - pull</command> from the main repository.</para> 23.1130 - </sect2> 23.1131 - 23.1132 - <sect2> 23.1133 - <title>A few things to watch out for</title> 23.1134 - 23.1135 - <para id="x_42e">MQ's support for working with a repository full of patches 23.1136 - is limited in a few small respects.</para> 23.1137 - 23.1138 - <para id="x_42f">MQ cannot automatically detect changes that you make to 23.1139 - the patch directory. If you <command role="hg-cmd">hg 23.1140 - pull</command>, manually edit, or <command role="hg-cmd">hg 23.1141 - update</command> changes to patches or the <filename 23.1142 - role="special">series</filename> file, you will have to 23.1143 - <command role="hg-cmd">hg qpop <option 23.1144 - role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and 23.1145 - then <command role="hg-cmd">hg qpush <option 23.1146 - role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in 23.1147 - the underlying repository to see those changes show up there. 23.1148 - If you forget to do this, you can confuse MQ's idea of which 23.1149 - patches are applied.</para> 23.1150 - 23.1151 - </sect2> 23.1152 - </sect1> 23.1153 - <sect1 id="sec:mq:tools"> 23.1154 - <title>Third party tools for working with patches</title> 23.1155 - 23.1156 - <para id="x_430">Once you've been working with patches for a while, you'll 23.1157 - find yourself hungry for tools that will help you to understand 23.1158 - and manipulate the patches you're dealing with.</para> 23.1159 - 23.1160 - <para id="x_431">The <command>diffstat</command> command 23.1161 - <citation>web:diffstat</citation> generates a histogram of the 23.1162 - modifications made to each file in a patch. It provides a good 23.1163 - way to <quote>get a sense of</quote> a patch&emdash;which files 23.1164 - it affects, and how much change it introduces to each file and 23.1165 - as a whole. (I find that it's a good idea to use 23.1166 - <command>diffstat</command>'s <option 23.1167 - role="cmd-opt-diffstat">-p</option> option as a matter of 23.1168 - course, as otherwise it will try to do clever things with 23.1169 - prefixes of file names that inevitably confuse at least 23.1170 - me.)</para> 23.1171 - 23.1172 -&interaction.mq.tools.tools; 23.1173 - 23.1174 - <para id="x_432">The <literal role="package">patchutils</literal> package 23.1175 - <citation>web:patchutils</citation> is invaluable. It provides a 23.1176 - set of small utilities that follow the <quote>Unix 23.1177 - philosophy;</quote> each does one useful thing with a patch. 23.1178 - The <literal role="package">patchutils</literal> command I use 23.1179 - most is <command>filterdiff</command>, which extracts subsets 23.1180 - from a patch file. For example, given a patch that modifies 23.1181 - hundreds of files across dozens of directories, a single 23.1182 - invocation of <command>filterdiff</command> can generate a 23.1183 - smaller patch that only touches files whose names match a 23.1184 - particular glob pattern. See <xref 23.1185 - linkend="mq-collab:tips:interdiff"/> for another 23.1186 - example.</para> 23.1187 - 23.1188 - </sect1> 23.1189 - <sect1> 23.1190 - <title>Good ways to work with patches</title> 23.1191 - 23.1192 - <para id="x_433">Whether you are working on a patch series to submit to a 23.1193 - free software or open source project, or a series that you 23.1194 - intend to treat as a sequence of regular changesets when you're 23.1195 - done, you can use some simple techniques to keep your work well 23.1196 - organized.</para> 23.1197 - 23.1198 - <para id="x_434">Give your patches descriptive names. A good name for a 23.1199 - patch might be <filename>rework-device-alloc.patch</filename>, 23.1200 - because it will immediately give you a hint what the purpose of 23.1201 - the patch is. Long names shouldn't be a problem; you won't be 23.1202 - typing the names often, but you <emphasis>will</emphasis> be 23.1203 - running commands like <command 23.1204 - role="hg-ext-mq">qapplied</command> and <command 23.1205 - role="hg-ext-mq">qtop</command> over and over. Good naming 23.1206 - becomes especially important when you have a number of patches 23.1207 - to work with, or if you are juggling a number of different tasks 23.1208 - and your patches only get a fraction of your attention.</para> 23.1209 - 23.1210 - <para id="x_435">Be aware of what patch you're working on. Use the <command 23.1211 - role="hg-ext-mq">qtop</command> command and skim over the text 23.1212 - of your patches frequently&emdash;for example, using <command 23.1213 - role="hg-cmd">hg tip <option 23.1214 - role="hg-opt-tip">-p</option></command>)&emdash;to be sure 23.1215 - of where you stand. I have several times worked on and <command 23.1216 - role="hg-ext-mq">qrefresh</command>ed a patch other than the 23.1217 - one I intended, and it's often tricky to migrate changes into 23.1218 - the right patch after making them in the wrong one.</para> 23.1219 - 23.1220 - <para id="x_436">For this reason, it is very much worth investing a little 23.1221 - time to learn how to use some of the third-party tools I 23.1222 - described in <xref linkend="sec:mq:tools"/>, 23.1223 - particularly 23.1224 - <command>diffstat</command> and <command>filterdiff</command>. 23.1225 - The former will give you a quick idea of what changes your patch 23.1226 - is making, while the latter makes it easy to splice hunks 23.1227 - selectively out of one patch and into another.</para> 23.1228 - 23.1229 - </sect1> 23.1230 - <sect1> 23.1231 - <title>MQ cookbook</title> 23.1232 - 23.1233 - <sect2> 23.1234 - <title>Manage <quote>trivial</quote> patches</title> 23.1235 - 23.1236 - <para id="x_437">Because the overhead of dropping files into a new 23.1237 - Mercurial repository is so low, it makes a lot of sense to 23.1238 - manage patches this way even if you simply want to make a few 23.1239 - changes to a source tarball that you downloaded.</para> 23.1240 - 23.1241 - <para id="x_438">Begin by downloading and unpacking the source tarball, and 23.1242 - turning it into a Mercurial repository.</para> 23.1243 - 23.1244 - &interaction.mq.tarball.download; 23.1245 - 23.1246 - <para id="x_439">Continue by creating a patch stack and making your 23.1247 - changes.</para> 23.1248 - 23.1249 - &interaction.mq.tarball.qinit; 23.1250 - 23.1251 - <para id="x_43a">Let's say a few weeks or months pass, and your package 23.1252 - author releases a new version. First, bring their changes 23.1253 - into the repository.</para> 23.1254 - 23.1255 - &interaction.mq.tarball.newsource; 23.1256 - 23.1257 - <para id="x_43b">The pipeline starting with <command role="hg-cmd">hg 23.1258 - locate</command> above deletes all files in the working 23.1259 - directory, so that <command role="hg-cmd">hg 23.1260 - commit</command>'s <option 23.1261 - role="hg-opt-commit">--addremove</option> option can 23.1262 - actually tell which files have really been removed in the 23.1263 - newer version of the source.</para> 23.1264 - 23.1265 - <para id="x_43c">Finally, you can apply your patches on top of the new 23.1266 - tree.</para> 23.1267 - 23.1268 - &interaction.mq.tarball.repush; 23.1269 - </sect2> 23.1270 - 23.1271 - <sect2 id="sec:mq:combine"> 23.1272 - <title>Combining entire patches</title> 23.1273 - 23.1274 - <para id="x_43d">MQ provides a command, <command 23.1275 - role="hg-ext-mq">qfold</command> that lets you combine 23.1276 - entire patches. This <quote>folds</quote> the patches you 23.1277 - name, in the order you name them, into the topmost applied 23.1278 - patch, and concatenates their descriptions onto the end of its 23.1279 - description. The patches that you fold must be unapplied 23.1280 - before you fold them.</para> 23.1281 - 23.1282 - <para id="x_43e">The order in which you fold patches matters. If your 23.1283 - topmost applied patch is <literal>foo</literal>, and you 23.1284 - <command role="hg-ext-mq">qfold</command> 23.1285 - <literal>bar</literal> and <literal>quux</literal> into it, 23.1286 - you will end up with a patch that has the same effect as if 23.1287 - you applied first <literal>foo</literal>, then 23.1288 - <literal>bar</literal>, followed by 23.1289 - <literal>quux</literal>.</para> 23.1290 - </sect2> 23.1291 - 23.1292 - <sect2> 23.1293 - <title>Merging part of one patch into another</title> 23.1294 - 23.1295 - <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into 23.1296 - another is more difficult than combining entire 23.1297 - patches.</para> 23.1298 - 23.1299 - <para id="x_440">If you want to move changes to entire files, you can use 23.1300 - <command>filterdiff</command>'s <option 23.1301 - role="cmd-opt-filterdiff">-i</option> and <option 23.1302 - role="cmd-opt-filterdiff">-x</option> options to choose the 23.1303 - modifications to snip out of one patch, concatenating its 23.1304 - output onto the end of the patch you want to merge into. You 23.1305 - usually won't need to modify the patch you've merged the 23.1306 - changes from. Instead, MQ will report some rejected hunks 23.1307 - when you <command role="hg-ext-mq">qpush</command> it (from 23.1308 - the hunks you moved into the other patch), and you can simply 23.1309 - <command role="hg-ext-mq">qrefresh</command> the patch to drop 23.1310 - the duplicate hunks.</para> 23.1311 - 23.1312 - <para id="x_441">If you have a patch that has multiple hunks modifying a 23.1313 - file, and you only want to move a few of those hunks, the job 23.1314 - becomes more messy, but you can still partly automate it. Use 23.1315 - <command>lsdiff -nvv</command> to print some metadata about 23.1316 - the patch.</para> 23.1317 - 23.1318 - &interaction.mq.tools.lsdiff; 23.1319 - 23.1320 - <para id="x_442">This command prints three different kinds of 23.1321 - number:</para> 23.1322 - <itemizedlist> 23.1323 - <listitem><para id="x_443">(in the first column) a <emphasis>file 23.1324 - number</emphasis> to identify each file modified in the 23.1325 - patch;</para> 23.1326 - </listitem> 23.1327 - <listitem><para id="x_444">(on the next line, indented) the line number 23.1328 - within a modified file where a hunk starts; and</para> 23.1329 - </listitem> 23.1330 - <listitem><para id="x_445">(on the same line) a <emphasis>hunk 23.1331 - number</emphasis> to identify that hunk.</para> 23.1332 - </listitem></itemizedlist> 23.1333 - 23.1334 - <para id="x_446">You'll have to use some visual inspection, and reading of 23.1335 - the patch, to identify the file and hunk numbers you'll want, 23.1336 - but you can then pass them to to 23.1337 - <command>filterdiff</command>'s <option 23.1338 - role="cmd-opt-filterdiff">--files</option> and <option 23.1339 - role="cmd-opt-filterdiff">--hunks</option> options, to 23.1340 - select exactly the file and hunk you want to extract.</para> 23.1341 - 23.1342 - <para id="x_447">Once you have this hunk, you can concatenate it onto the 23.1343 - end of your destination patch and continue with the remainder 23.1344 - of <xref linkend="sec:mq:combine"/>.</para> 23.1345 - 23.1346 - </sect2> 23.1347 - </sect1> 23.1348 - <sect1> 23.1349 - <title>Differences between quilt and MQ</title> 23.1350 - 23.1351 - <para id="x_448">If you are already familiar with quilt, MQ provides a 23.1352 - similar command set. There are a few differences in the way 23.1353 - that it works.</para> 23.1354 - 23.1355 - <para id="x_449">You will already have noticed that most quilt commands have 23.1356 - MQ counterparts that simply begin with a 23.1357 - <quote><literal>q</literal></quote>. The exceptions are quilt's 23.1358 - <literal>add</literal> and <literal>remove</literal> commands, 23.1359 - the counterparts for which are the normal Mercurial <command 23.1360 - role="hg-cmd">hg add</command> and <command role="hg-cmd">hg 23.1361 - remove</command> commands. There is no MQ equivalent of the 23.1362 - quilt <literal>edit</literal> command.</para> 23.1363 - 23.1364 - </sect1> 23.1365 -</chapter> 23.1366 - 23.1367 -<!-- 23.1368 -local variables: 23.1369 -sgml-parent-document: ("00book.xml" "book" "chapter") 23.1370 -end: 23.1371 --->
24.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 24.2 +++ b/en/ch11-template.xml Thu May 07 21:07:35 2009 -0700 24.3 @@ -0,0 +1,685 @@ 24.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 24.5 + 24.6 +<chapter id="chap:template"> 24.7 + <?dbhtml filename="customizing-the-output-of-mercurial.html"?> 24.8 + <title>Customizing the output of Mercurial</title> 24.9 + 24.10 + <para id="x_578">Mercurial provides a powerful mechanism to let you control how 24.11 + it displays information. The mechanism is based on templates. 24.12 + You can use templates to generate specific output for a single 24.13 + command, or to customize the entire appearance of the built-in web 24.14 + interface.</para> 24.15 + 24.16 + <sect1 id="sec:style"> 24.17 + <title>Using precanned output styles</title> 24.18 + 24.19 + <para id="x_579">Packaged with Mercurial are some output styles that you can 24.20 + use immediately. A style is simply a precanned template that 24.21 + someone wrote and installed somewhere that Mercurial can 24.22 + find.</para> 24.23 + 24.24 + <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's 24.25 + review its normal output.</para> 24.26 + 24.27 + &interaction.template.simple.normal; 24.28 + 24.29 + <para id="x_57b">This is somewhat informative, but it takes up a lot of 24.30 + space&emdash;five lines of output per changeset. The 24.31 + <literal>compact</literal> style reduces this to three lines, 24.32 + presented in a sparse manner.</para> 24.33 + 24.34 + &interaction.template.simple.compact; 24.35 + 24.36 + <para id="x_57c">The <literal>changelog</literal> style hints at the 24.37 + expressive power of Mercurial's templating engine. This style 24.38 + attempts to follow the GNU Project's changelog 24.39 + guidelines<citation>web:changelog</citation>.</para> 24.40 + 24.41 + &interaction.template.simple.changelog; 24.42 + 24.43 + <para id="x_57d">You will not be shocked to learn that Mercurial's default 24.44 + output style is named <literal>default</literal>.</para> 24.45 + 24.46 + <sect2> 24.47 + <title>Setting a default style</title> 24.48 + 24.49 + <para id="x_57e">You can modify the output style that Mercurial will use 24.50 + for every command by editing your <filename 24.51 + role="special">~/.hgrc</filename> file, naming the style 24.52 + you would prefer to use.</para> 24.53 + 24.54 + <programlisting>[ui] 24.55 +style = compact</programlisting> 24.56 + 24.57 + <para id="x_57f">If you write a style of your own, you can use it by either 24.58 + providing the path to your style file, or copying your style 24.59 + file into a location where Mercurial can find it (typically 24.60 + the <literal>templates</literal> subdirectory of your 24.61 + Mercurial install directory).</para> 24.62 + </sect2> 24.63 + </sect1> 24.64 + 24.65 + <sect1> 24.66 + <title>Commands that support styles and templates</title> 24.67 + 24.68 + <para id="x_580">All of Mercurial's 24.69 + <quote><literal>log</literal>-like</quote> commands let you use 24.70 + styles and templates: <command role="hg-cmd">hg 24.71 + incoming</command>, <command role="hg-cmd">hg log</command>, 24.72 + <command role="hg-cmd">hg outgoing</command>, and <command 24.73 + role="hg-cmd">hg tip</command>.</para> 24.74 + 24.75 + <para id="x_581">As I write this manual, these are so far the only commands 24.76 + that support styles and templates. Since these are the most 24.77 + important commands that need customizable output, there has been 24.78 + little pressure from the Mercurial user community to add style 24.79 + and template support to other commands.</para> 24.80 + </sect1> 24.81 + 24.82 + <sect1> 24.83 + <title>The basics of templating</title> 24.84 + 24.85 + <para id="x_582">At its simplest, a Mercurial template is a piece of text. 24.86 + Some of the text never changes, while other parts are 24.87 + <emphasis>expanded</emphasis>, or replaced with new text, when 24.88 + necessary.</para> 24.89 + 24.90 + <para id="x_583">Before we continue, let's look again at a simple example of 24.91 + Mercurial's normal output.</para> 24.92 + 24.93 + &interaction.template.simple.normal; 24.94 + 24.95 + <para id="x_584">Now, let's run the same command, but using a template to 24.96 + change its output.</para> 24.97 + 24.98 + &interaction.template.simple.simplest; 24.99 + 24.100 + <para id="x_585">The example above illustrates the simplest possible 24.101 + template; it's just a piece of static text, printed once for 24.102 + each changeset. The <option 24.103 + role="hg-opt-log">--template</option> option to the <command 24.104 + role="hg-cmd">hg log</command> command tells Mercurial to use 24.105 + the given text as the template when printing each 24.106 + changeset.</para> 24.107 + 24.108 + <para id="x_586">Notice that the template string above ends with the text 24.109 + <quote><literal>\n</literal></quote>. This is an 24.110 + <emphasis>escape sequence</emphasis>, telling Mercurial to print 24.111 + a newline at the end of each template item. If you omit this 24.112 + newline, Mercurial will run each piece of output together. See 24.113 + <xref linkend="sec:template:escape"/> for more details 24.114 + of escape sequences.</para> 24.115 + 24.116 + <para id="x_587">A template that prints a fixed string of text all the time 24.117 + isn't very useful; let's try something a bit more 24.118 + complex.</para> 24.119 + 24.120 + &interaction.template.simple.simplesub; 24.121 + 24.122 + <para id="x_588">As you can see, the string 24.123 + <quote><literal>{desc}</literal></quote> in the template has 24.124 + been replaced in the output with the description of each 24.125 + changeset. Every time Mercurial finds text enclosed in curly 24.126 + braces (<quote><literal>{</literal></quote> and 24.127 + <quote><literal>}</literal></quote>), it will try to replace the 24.128 + braces and text with the expansion of whatever is inside. To 24.129 + print a literal curly brace, you must escape it, as described in 24.130 + <xref linkend="sec:template:escape"/>.</para> 24.131 + </sect1> 24.132 + 24.133 + <sect1 id="sec:template:keyword"> 24.134 + <title>Common template keywords</title> 24.135 + 24.136 + <para id="x_589">You can start writing simple templates immediately using the 24.137 + keywords below.</para> 24.138 + 24.139 + <itemizedlist> 24.140 + <listitem><para id="x_58a"><literal 24.141 + role="template-keyword">author</literal>: String. The 24.142 + unmodified author of the changeset.</para> 24.143 + </listitem> 24.144 + <listitem><para id="x_58b"><literal 24.145 + role="template-keyword">branches</literal>: String. The 24.146 + name of the branch on which the changeset was committed. 24.147 + Will be empty if the branch name was 24.148 + <literal>default</literal>.</para> 24.149 + </listitem> 24.150 + <listitem><para id="x_58c"><literal role="template-keyword">date</literal>: 24.151 + Date information. The date when the changeset was 24.152 + committed. This is <emphasis>not</emphasis> human-readable; 24.153 + you must pass it through a filter that will render it 24.154 + appropriately. See <xref 24.155 + linkend="sec:template:filter"/> for more information 24.156 + on filters. The date is expressed as a pair of numbers. The 24.157 + first number is a Unix UTC timestamp (seconds since January 24.158 + 1, 1970); the second is the offset of the committer's 24.159 + timezone from UTC, in seconds.</para> 24.160 + </listitem> 24.161 + <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>: 24.162 + String. The text of the changeset description.</para> 24.163 + </listitem> 24.164 + <listitem><para id="x_58e"><literal 24.165 + role="template-keyword">files</literal>: List of strings. 24.166 + All files modified, added, or removed by this 24.167 + changeset.</para> 24.168 + </listitem> 24.169 + <listitem><para id="x_58f"><literal 24.170 + role="template-keyword">file_adds</literal>: List of 24.171 + strings. Files added by this changeset.</para> 24.172 + </listitem> 24.173 + <listitem><para id="x_590"><literal 24.174 + role="template-keyword">file_dels</literal>: List of 24.175 + strings. Files removed by this changeset.</para> 24.176 + </listitem> 24.177 + <listitem><para id="x_591"><literal role="template-keyword">node</literal>: 24.178 + String. The changeset identification hash, as a 24.179 + 40-character hexadecimal string.</para> 24.180 + </listitem> 24.181 + <listitem><para id="x_592"><literal 24.182 + role="template-keyword">parents</literal>: List of 24.183 + strings. The parents of the changeset.</para> 24.184 + </listitem> 24.185 + <listitem><para id="x_593"><literal role="template-keyword">rev</literal>: 24.186 + Integer. The repository-local changeset revision 24.187 + number.</para> 24.188 + </listitem> 24.189 + <listitem><para id="x_594"><literal role="template-keyword">tags</literal>: 24.190 + List of strings. Any tags associated with the 24.191 + changeset.</para> 24.192 + </listitem> 24.193 + </itemizedlist> 24.194 + 24.195 + <para id="x_595">A few simple experiments will show us what to expect when we 24.196 + use these keywords; you can see the results below.</para> 24.197 + 24.198 + &interaction.template.simple.keywords; 24.199 + 24.200 + <para id="x_596">As we noted above, the date keyword does not produce 24.201 + human-readable output, so we must treat it specially. This 24.202 + involves using a <emphasis>filter</emphasis>, about which more 24.203 + in <xref linkend="sec:template:filter"/>.</para> 24.204 + 24.205 + &interaction.template.simple.datekeyword; 24.206 + </sect1> 24.207 + 24.208 + <sect1 id="sec:template:escape"> 24.209 + <title>Escape sequences</title> 24.210 + 24.211 + <para id="x_597">Mercurial's templating engine recognises the most commonly 24.212 + used escape sequences in strings. When it sees a backslash 24.213 + (<quote><literal>\</literal></quote>) character, it looks at the 24.214 + following character and substitutes the two characters with a 24.215 + single replacement, as described below.</para> 24.216 + 24.217 + <itemizedlist> 24.218 + <listitem><para id="x_598"><literal>\</literal>: 24.219 + Backslash, <quote><literal>\</literal></quote>, ASCII 24.220 + 134.</para> 24.221 + </listitem> 24.222 + <listitem><para id="x_599"><literal>\n</literal>: Newline, 24.223 + ASCII 12.</para> 24.224 + </listitem> 24.225 + <listitem><para id="x_59a"><literal>\r</literal>: Carriage 24.226 + return, ASCII 15.</para> 24.227 + </listitem> 24.228 + <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII 24.229 + 11.</para> 24.230 + </listitem> 24.231 + <listitem><para id="x_59c"><literal>\v</literal>: Vertical 24.232 + tab, ASCII 13.</para> 24.233 + </listitem> 24.234 + <listitem><para id="x_59d"><literal>\{</literal>: Open curly 24.235 + brace, <quote><literal>{</literal></quote>, ASCII 24.236 + 173.</para> 24.237 + </listitem> 24.238 + <listitem><para id="x_59e"><literal>\}</literal>: Close curly 24.239 + brace, <quote><literal>}</literal></quote>, ASCII 24.240 + 175.</para> 24.241 + </listitem></itemizedlist> 24.242 + 24.243 + <para id="x_59f">As indicated above, if you want the expansion of a template 24.244 + to contain a literal <quote><literal>\</literal></quote>, 24.245 + <quote><literal>{</literal></quote>, or 24.246 + <quote><literal>{</literal></quote> character, you must escape 24.247 + it.</para> 24.248 + </sect1> 24.249 + 24.250 + <sect1 id="sec:template:filter"> 24.251 + <title>Filtering keywords to change their results</title> 24.252 + 24.253 + <para id="x_5a0">Some of the results of template expansion are not 24.254 + immediately easy to use. Mercurial lets you specify an optional 24.255 + chain of <emphasis>filters</emphasis> to modify the result of 24.256 + expanding a keyword. You have already seen a common filter, 24.257 + <literal role="template-kw-filt-date">isodate</literal>, in 24.258 + action above, to make a date readable.</para> 24.259 + 24.260 + <para id="x_5a1">Below is a list of the most commonly used filters that 24.261 + Mercurial supports. While some filters can be applied to any 24.262 + text, others can only be used in specific circumstances. The 24.263 + name of each filter is followed first by an indication of where 24.264 + it can be used, then a description of its effect.</para> 24.265 + 24.266 + <itemizedlist> 24.267 + <listitem><para id="x_5a2"><literal 24.268 + role="template-filter">addbreaks</literal>: Any text. Add 24.269 + an XHTML <quote><literal><br/></literal></quote> tag 24.270 + before the end of every line except the last. For example, 24.271 + <quote><literal>foo\nbar</literal></quote> becomes 24.272 + <quote><literal>foo<br/>\nbar</literal></quote>.</para> 24.273 + </listitem> 24.274 + <listitem><para id="x_5a3"><literal 24.275 + role="template-kw-filt-date">age</literal>: <literal 24.276 + role="template-keyword">date</literal> keyword. Render 24.277 + the age of the date, relative to the current time. Yields a 24.278 + string like <quote><literal>10 24.279 + minutes</literal></quote>.</para> 24.280 + </listitem> 24.281 + <listitem><para id="x_5a4"><literal 24.282 + role="template-filter">basename</literal>: Any text, but 24.283 + most useful for the <literal 24.284 + role="template-keyword">files</literal> keyword and its 24.285 + relatives. Treat the text as a path, and return the 24.286 + basename. For example, 24.287 + <quote><literal>foo/bar/baz</literal></quote> becomes 24.288 + <quote><literal>baz</literal></quote>.</para> 24.289 + </listitem> 24.290 + <listitem><para id="x_5a5"><literal 24.291 + role="template-kw-filt-date">date</literal>: <literal 24.292 + role="template-keyword">date</literal> keyword. Render a 24.293 + date in a similar format to the Unix <literal 24.294 + role="template-keyword">date</literal> command, but with 24.295 + timezone included. Yields a string like <quote><literal>Mon 24.296 + Sep 04 15:13:13 2006 -0700</literal></quote>.</para> 24.297 + </listitem> 24.298 + <listitem><para id="x_5a6"><literal 24.299 + role="template-kw-filt-author">domain</literal>: Any text, 24.300 + but most useful for the <literal 24.301 + role="template-keyword">author</literal> keyword. Finds 24.302 + the first string that looks like an email address, and 24.303 + extract just the domain component. For example, 24.304 + <quote><literal>Bryan O'Sullivan 24.305 + <bos@serpentine.com></literal></quote> becomes 24.306 + <quote><literal>serpentine.com</literal></quote>.</para> 24.307 + </listitem> 24.308 + <listitem><para id="x_5a7"><literal 24.309 + role="template-kw-filt-author">email</literal>: Any text, 24.310 + but most useful for the <literal 24.311 + role="template-keyword">author</literal> keyword. Extract 24.312 + the first string that looks like an email address. For 24.313 + example, <quote><literal>Bryan O'Sullivan 24.314 + <bos@serpentine.com></literal></quote> becomes 24.315 + <quote><literal>bos@serpentine.com</literal></quote>.</para> 24.316 + </listitem> 24.317 + <listitem><para id="x_5a8"><literal 24.318 + role="template-filter">escape</literal>: Any text. 24.319 + Replace the special XML/XHTML characters 24.320 + <quote><literal>&</literal></quote>, 24.321 + <quote><literal><</literal></quote> and 24.322 + <quote><literal>></literal></quote> with XML 24.323 + entities.</para> 24.324 + </listitem> 24.325 + <listitem><para id="x_5a9"><literal 24.326 + role="template-filter">fill68</literal>: Any text. Wrap 24.327 + the text to fit in 68 columns. This is useful before you 24.328 + pass text through the <literal 24.329 + role="template-filter">tabindent</literal> filter, and 24.330 + still want it to fit in an 80-column fixed-font 24.331 + window.</para> 24.332 + </listitem> 24.333 + <listitem><para id="x_5aa"><literal 24.334 + role="template-filter">fill76</literal>: Any text. Wrap 24.335 + the text to fit in 76 columns.</para> 24.336 + </listitem> 24.337 + <listitem><para id="x_5ab"><literal 24.338 + role="template-filter">firstline</literal>: Any text. 24.339 + Yield the first line of text, without any trailing 24.340 + newlines.</para> 24.341 + </listitem> 24.342 + <listitem><para id="x_5ac"><literal 24.343 + role="template-kw-filt-date">hgdate</literal>: <literal 24.344 + role="template-keyword">date</literal> keyword. Render 24.345 + the date as a pair of readable numbers. Yields a string 24.346 + like <quote><literal>1157407993 24.347 + 25200</literal></quote>.</para> 24.348 + </listitem> 24.349 + <listitem><para id="x_5ad"><literal 24.350 + role="template-kw-filt-date">isodate</literal>: <literal 24.351 + role="template-keyword">date</literal> keyword. Render 24.352 + the date as a text string in ISO 8601 format. Yields a 24.353 + string like <quote><literal>2006-09-04 15:13:13 24.354 + -0700</literal></quote>.</para> 24.355 + </listitem> 24.356 + <listitem><para id="x_5ae"><literal 24.357 + role="template-filter">obfuscate</literal>: Any text, but 24.358 + most useful for the <literal 24.359 + role="template-keyword">author</literal> keyword. Yield 24.360 + the input text rendered as a sequence of XML entities. This 24.361 + helps to defeat some particularly stupid screen-scraping 24.362 + email harvesting spambots.</para> 24.363 + </listitem> 24.364 + <listitem><para id="x_5af"><literal 24.365 + role="template-kw-filt-author">person</literal>: Any text, 24.366 + but most useful for the <literal 24.367 + role="template-keyword">author</literal> keyword. Yield 24.368 + the text before an email address. For example, 24.369 + <quote><literal>Bryan O'Sullivan 24.370 + <bos@serpentine.com></literal></quote> becomes 24.371 + <quote><literal>Bryan O'Sullivan</literal></quote>.</para> 24.372 + </listitem> 24.373 + <listitem><para id="x_5b0"><literal 24.374 + role="template-kw-filt-date">rfc822date</literal>: 24.375 + <literal role="template-keyword">date</literal> keyword. 24.376 + Render a date using the same format used in email headers. 24.377 + Yields a string like <quote><literal>Mon, 04 Sep 2006 24.378 + 15:13:13 -0700</literal></quote>.</para> 24.379 + </listitem> 24.380 + <listitem><para id="x_5b1"><literal 24.381 + role="template-kw-filt-node">short</literal>: Changeset 24.382 + hash. Yield the short form of a changeset hash, i.e. a 24.383 + 12-character hexadecimal string.</para> 24.384 + </listitem> 24.385 + <listitem><para id="x_5b2"><literal 24.386 + role="template-kw-filt-date">shortdate</literal>: <literal 24.387 + role="template-keyword">date</literal> keyword. Render 24.388 + the year, month, and day of the date. Yields a string like 24.389 + <quote><literal>2006-09-04</literal></quote>.</para> 24.390 + </listitem> 24.391 + <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>: 24.392 + Any text. Strip all leading and trailing whitespace from 24.393 + the string.</para> 24.394 + </listitem> 24.395 + <listitem><para id="x_5b4"><literal 24.396 + role="template-filter">tabindent</literal>: Any text. 24.397 + Yield the text, with every line except the first starting 24.398 + with a tab character.</para> 24.399 + </listitem> 24.400 + <listitem><para id="x_5b5"><literal 24.401 + role="template-filter">urlescape</literal>: Any text. 24.402 + Escape all characters that are considered 24.403 + <quote>special</quote> by URL parsers. For example, 24.404 + <literal>foo bar</literal> becomes 24.405 + <literal>foo%20bar</literal>.</para> 24.406 + </listitem> 24.407 + <listitem><para id="x_5b6"><literal 24.408 + role="template-kw-filt-author">user</literal>: Any text, 24.409 + but most useful for the <literal 24.410 + role="template-keyword">author</literal> keyword. Return 24.411 + the <quote>user</quote> portion of an email address. For 24.412 + example, <quote><literal>Bryan O'Sullivan 24.413 + <bos@serpentine.com></literal></quote> becomes 24.414 + <quote><literal>bos</literal></quote>.</para> 24.415 + </listitem> 24.416 + </itemizedlist> 24.417 + 24.418 + &interaction.template.simple.manyfilters; 24.419 + 24.420 + <note> 24.421 + <para id="x_5b7"> If you try to apply a filter to a piece of data that it 24.422 + cannot process, Mercurial will fail and print a Python 24.423 + exception. For example, trying to run the output of the 24.424 + <literal role="template-keyword">desc</literal> keyword into 24.425 + the <literal role="template-kw-filt-date">isodate</literal> 24.426 + filter is not a good idea.</para> 24.427 + </note> 24.428 + 24.429 + <sect2> 24.430 + <title>Combining filters</title> 24.431 + 24.432 + <para id="x_5b8">It is easy to combine filters to yield output in the form 24.433 + you would like. The following chain of filters tidies up a 24.434 + description, then makes sure that it fits cleanly into 68 24.435 + columns, then indents it by a further 8 characters (at least 24.436 + on Unix-like systems, where a tab is conventionally 8 24.437 + characters wide).</para> 24.438 + 24.439 + &interaction.template.simple.combine; 24.440 + 24.441 + <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a 24.442 + tab character) in the template to force the first line to be 24.443 + indented; this is necessary since <literal 24.444 + role="template-keyword">tabindent</literal> indents all 24.445 + lines <emphasis>except</emphasis> the first.</para> 24.446 + 24.447 + <para id="x_5ba">Keep in mind that the order of filters in a chain is 24.448 + significant. The first filter is applied to the result of the 24.449 + keyword; the second to the result of the first filter; and so 24.450 + on. For example, using <literal>fill68|tabindent</literal> 24.451 + gives very different results from 24.452 + <literal>tabindent|fill68</literal>.</para> 24.453 + </sect2> 24.454 + </sect1> 24.455 + 24.456 + <sect1> 24.457 + <title>From templates to styles</title> 24.458 + 24.459 + <para id="x_5bb">A command line template provides a quick and simple way to 24.460 + format some output. Templates can become verbose, though, and 24.461 + it's useful to be able to give a template a name. A style file 24.462 + is a template with a name, stored in a file.</para> 24.463 + 24.464 + <para id="x_5bc">More than that, using a style file unlocks the power of 24.465 + Mercurial's templating engine in ways that are not possible 24.466 + using the command line <option 24.467 + role="hg-opt-log">--template</option> option.</para> 24.468 + 24.469 + <sect2> 24.470 + <title>The simplest of style files</title> 24.471 + 24.472 + <para id="x_5bd">Our simple style file contains just one line:</para> 24.473 + 24.474 + &interaction.template.simple.rev; 24.475 + 24.476 + <para id="x_5be">This tells Mercurial, <quote>if you're printing a 24.477 + changeset, use the text on the right as the 24.478 + template</quote>.</para> 24.479 + </sect2> 24.480 + 24.481 + <sect2> 24.482 + <title>Style file syntax</title> 24.483 + 24.484 + <para id="x_5bf">The syntax rules for a style file are simple.</para> 24.485 + 24.486 + <itemizedlist> 24.487 + <listitem><para id="x_5c0">The file is processed one line at a 24.488 + time.</para> 24.489 + </listitem> 24.490 + <listitem><para id="x_5c1">Leading and trailing white space are 24.491 + ignored.</para> 24.492 + </listitem> 24.493 + <listitem><para id="x_5c2">Empty lines are skipped.</para> 24.494 + </listitem> 24.495 + <listitem><para id="x_5c3">If a line starts with either of the characters 24.496 + <quote><literal>#</literal></quote> or 24.497 + <quote><literal>;</literal></quote>, the entire line is 24.498 + treated as a comment, and skipped as if empty.</para> 24.499 + </listitem> 24.500 + <listitem><para id="x_5c4">A line starts with a keyword. This must start 24.501 + with an alphabetic character or underscore, and can 24.502 + subsequently contain any alphanumeric character or 24.503 + underscore. (In regexp notation, a keyword must match 24.504 + <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para> 24.505 + </listitem> 24.506 + <listitem><para id="x_5c5">The next element must be an 24.507 + <quote><literal>=</literal></quote> character, which can 24.508 + be preceded or followed by an arbitrary amount of white 24.509 + space.</para> 24.510 + </listitem> 24.511 + <listitem><para id="x_5c6">If the rest of the line starts and ends with 24.512 + matching quote characters (either single or double quote), 24.513 + it is treated as a template body.</para> 24.514 + </listitem> 24.515 + <listitem><para id="x_5c7">If the rest of the line <emphasis>does 24.516 + not</emphasis> start with a quote character, it is 24.517 + treated as the name of a file; the contents of this file 24.518 + will be read and used as a template body.</para> 24.519 + </listitem></itemizedlist> 24.520 + </sect2> 24.521 + </sect1> 24.522 + 24.523 + <sect1> 24.524 + <title>Style files by example</title> 24.525 + 24.526 + <para id="x_5c8">To illustrate how to write a style file, we will construct a 24.527 + few by example. Rather than provide a complete style file and 24.528 + walk through it, we'll mirror the usual process of developing a 24.529 + style file by starting with something very simple, and walking 24.530 + through a series of successively more complete examples.</para> 24.531 + 24.532 + <sect2> 24.533 + <title>Identifying mistakes in style files</title> 24.534 + 24.535 + <para id="x_5c9">If Mercurial encounters a problem in a style file you are 24.536 + working on, it prints a terse error message that, once you 24.537 + figure out what it means, is actually quite useful.</para> 24.538 + 24.539 +&interaction.template.svnstyle.syntax.input; 24.540 + 24.541 + <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to 24.542 + define a <literal>changeset</literal> keyword, but forgets to 24.543 + give any content for it. When instructed to use this style 24.544 + file, Mercurial promptly complains.</para> 24.545 + 24.546 + &interaction.template.svnstyle.syntax.error; 24.547 + 24.548 + <para id="x_5cb">This error message looks intimidating, but it is not too 24.549 + hard to follow.</para> 24.550 + 24.551 + <itemizedlist> 24.552 + <listitem><para id="x_5cc">The first component is simply Mercurial's way 24.553 + of saying <quote>I am giving up</quote>.</para> 24.554 + <programlisting>___abort___: broken.style:1: parse error</programlisting> 24.555 + </listitem> 24.556 + <listitem><para id="x_5cd">Next comes the name of the style file that 24.557 + contains the error.</para> 24.558 + <programlisting>abort: ___broken.style___:1: parse error</programlisting> 24.559 + </listitem> 24.560 + <listitem><para id="x_5ce">Following the file name is the line number 24.561 + where the error was encountered.</para> 24.562 + <programlisting>abort: broken.style:___1___: parse error</programlisting> 24.563 + </listitem> 24.564 + <listitem><para id="x_5cf">Finally, a description of what went 24.565 + wrong.</para> 24.566 + <programlisting>abort: broken.style:1: ___parse error___</programlisting> 24.567 + </listitem> 24.568 + <listitem><para id="x_5d0">The description of the problem is not always 24.569 + clear (as in this case), but even when it is cryptic, it 24.570 + is almost always trivial to visually inspect the offending 24.571 + line in the style file and see what is wrong.</para> 24.572 + </listitem> 24.573 + </itemizedlist> 24.574 + </sect2> 24.575 + 24.576 + <sect2> 24.577 + <title>Uniquely identifying a repository</title> 24.578 + 24.579 + <para id="x_5d1">If you would like to be able to identify a Mercurial 24.580 + repository <quote>fairly uniquely</quote> using a short string 24.581 + as an identifier, you can use the first revision in the 24.582 + repository.</para> 24.583 + 24.584 + &interaction.template.svnstyle.id; 24.585 + 24.586 + <para id="x_5d2">This is likely to be unique, and so it is 24.587 + useful in many cases. There are a few caveats.</para> 24.588 + <itemizedlist> 24.589 + <listitem><para id="x_5d3">It will not work in a completely empty 24.590 + repository, because such a repository does not have a 24.591 + revision zero.</para> 24.592 + </listitem> 24.593 + <listitem><para id="x_5d4">Neither will it work in the (extremely rare) 24.594 + case where a repository is a merge of two or more formerly 24.595 + independent repositories, and you still have those 24.596 + repositories around.</para> 24.597 + </listitem></itemizedlist> 24.598 + <para id="x_5d5">Here are some uses to which you could put this 24.599 + identifier:</para> 24.600 + <itemizedlist> 24.601 + <listitem><para id="x_5d6">As a key into a table for a database that 24.602 + manages repositories on a server.</para> 24.603 + </listitem> 24.604 + <listitem><para id="x_5d7">As half of a {<emphasis>repository 24.605 + ID</emphasis>, <emphasis>revision ID</emphasis>} tuple. 24.606 + Save this information away when you run an automated build 24.607 + or other activity, so that you can <quote>replay</quote> 24.608 + the build later if necessary.</para> 24.609 + </listitem> 24.610 + </itemizedlist> 24.611 + </sect2> 24.612 + 24.613 + <sect2> 24.614 + <title>Listing files on multiple lines</title> 24.615 + 24.616 + <para id="x_714">Suppose we want to list the files changed by a changeset, 24.617 + one per line, with a little indentation before each file 24.618 + name.</para> 24.619 + 24.620 + &interaction.ch10-multiline.go; 24.621 + </sect2> 24.622 + 24.623 + <sect2> 24.624 + <title>Mimicking Subversion's output</title> 24.625 + 24.626 + <para id="x_5d8">Let's try to emulate the default output format used by 24.627 + another revision control tool, Subversion.</para> 24.628 + 24.629 + &interaction.template.svnstyle.short; 24.630 + 24.631 + <para id="x_5d9">Since Subversion's output style is fairly simple, it is 24.632 + easy to copy-and-paste a hunk of its output into a file, and 24.633 + replace the text produced above by Subversion with the 24.634 + template values we'd like to see expanded.</para> 24.635 + 24.636 + &interaction.template.svnstyle.template; 24.637 + 24.638 + <para id="x_5da">There are a few small ways in which this template deviates 24.639 + from the output produced by Subversion.</para> 24.640 + <itemizedlist> 24.641 + <listitem><para id="x_5db">Subversion prints a <quote>readable</quote> 24.642 + date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the 24.643 + example output above) in parentheses. Mercurial's 24.644 + templating engine does not provide a way to display a date 24.645 + in this format without also printing the time and time 24.646 + zone.</para> 24.647 + </listitem> 24.648 + <listitem><para id="x_5dc">We emulate Subversion's printing of 24.649 + <quote>separator</quote> lines full of 24.650 + <quote><literal>-</literal></quote> characters by ending 24.651 + the template with such a line. We use the templating 24.652 + engine's <literal role="template-keyword">header</literal> 24.653 + keyword to print a separator line as the first line of 24.654 + output (see below), thus achieving similar output to 24.655 + Subversion.</para> 24.656 + </listitem> 24.657 + <listitem><para id="x_5dd">Subversion's output includes a count in the 24.658 + header of the number of lines in the commit message. We 24.659 + cannot replicate this in Mercurial; the templating engine 24.660 + does not currently provide a filter that counts the number 24.661 + of lines the template generates.</para> 24.662 + </listitem></itemizedlist> 24.663 + <para id="x_5de">It took me no more than a minute or two of work to replace 24.664 + literal text from an example of Subversion's output with some 24.665 + keywords and filters to give the template above. The style 24.666 + file simply refers to the template.</para> 24.667 + 24.668 + &interaction.template.svnstyle.style; 24.669 + 24.670 + <para id="x_5df">We could have included the text of the template file 24.671 + directly in the style file by enclosing it in quotes and 24.672 + replacing the newlines with 24.673 + <quote><literal>\n</literal></quote> sequences, but it would 24.674 + have made the style file too difficult to read. Readability 24.675 + is a good guide when you're trying to decide whether some text 24.676 + belongs in a style file, or in a template file that the style 24.677 + file points to. If the style file will look too big or 24.678 + cluttered if you insert a literal piece of text, drop it into 24.679 + a template instead.</para> 24.680 + </sect2> 24.681 + </sect1> 24.682 +</chapter> 24.683 + 24.684 +<!-- 24.685 +local variables: 24.686 +sgml-parent-document: ("00book.xml" "book" "chapter") 24.687 +end: 24.688 +-->
25.1 --- a/en/ch12-mq-collab.xml Thu May 07 21:06:49 2009 -0700 25.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 25.3 @@ -1,518 +0,0 @@ 25.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 25.5 - 25.6 -<chapter id="chap:mq-collab"> 25.7 - <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?> 25.8 - <title>Advanced uses of Mercurial Queues</title> 25.9 - 25.10 - <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial 25.11 - Queues, use of a little discipline and some of MQ's less 25.12 - frequently used capabilities makes it possible to work in 25.13 - complicated development environments.</para> 25.14 - 25.15 - <para id="x_15e">In this chapter, I will use as an example a technique I have 25.16 - used to manage the development of an Infiniband device driver for 25.17 - the Linux kernel. The driver in question is large (at least as 25.18 - drivers go), with 25,000 lines of code spread across 35 source 25.19 - files. It is maintained by a small team of developers.</para> 25.20 - 25.21 - <para id="x_15f">While much of the material in this chapter is specific to 25.22 - Linux, the same principles apply to any code base for which you're 25.23 - not the primary owner, and upon which you need to do a lot of 25.24 - development.</para> 25.25 - 25.26 - <sect1> 25.27 - <title>The problem of many targets</title> 25.28 - 25.29 - <para id="x_160">The Linux kernel changes rapidly, and has never been 25.30 - internally stable; developers frequently make drastic changes 25.31 - between releases. This means that a version of the driver that 25.32 - works well with a particular released version of the kernel will 25.33 - not even <emphasis>compile</emphasis> correctly against, 25.34 - typically, any other version.</para> 25.35 - 25.36 - <para id="x_161">To maintain a driver, we have to keep a number of distinct 25.37 - versions of Linux in mind.</para> 25.38 - <itemizedlist> 25.39 - <listitem><para id="x_162">One target is the main Linux kernel development 25.40 - tree. Maintenance of the code is in this case partly shared 25.41 - by other developers in the kernel community, who make 25.42 - <quote>drive-by</quote> modifications to the driver as they 25.43 - develop and refine kernel subsystems.</para> 25.44 - </listitem> 25.45 - <listitem><para id="x_163">We also maintain a number of 25.46 - <quote>backports</quote> to older versions of the Linux 25.47 - kernel, to support the needs of customers who are running 25.48 - older Linux distributions that do not incorporate our 25.49 - drivers. (To <emphasis>backport</emphasis> a piece of code 25.50 - is to modify it to work in an older version of its target 25.51 - environment than the version it was developed for.)</para> 25.52 - </listitem> 25.53 - <listitem><para id="x_164">Finally, we make software releases on a schedule 25.54 - that is necessarily not aligned with those used by Linux 25.55 - distributors and kernel developers, so that we can deliver 25.56 - new features to customers without forcing them to upgrade 25.57 - their entire kernels or distributions.</para> 25.58 - </listitem></itemizedlist> 25.59 - 25.60 - <sect2> 25.61 - <title>Tempting approaches that don't work well</title> 25.62 - 25.63 - <para id="x_165">There are two <quote>standard</quote> ways to maintain a 25.64 - piece of software that has to target many different 25.65 - environments.</para> 25.66 - 25.67 - <para id="x_166">The first is to maintain a number of branches, each 25.68 - intended for a single target. The trouble with this approach 25.69 - is that you must maintain iron discipline in the flow of 25.70 - changes between repositories. A new feature or bug fix must 25.71 - start life in a <quote>pristine</quote> repository, then 25.72 - percolate out to every backport repository. Backport changes 25.73 - are more limited in the branches they should propagate to; a 25.74 - backport change that is applied to a branch where it doesn't 25.75 - belong will probably stop the driver from compiling.</para> 25.76 - 25.77 - <para id="x_167">The second is to maintain a single source tree filled with 25.78 - conditional statements that turn chunks of code on or off 25.79 - depending on the intended target. Because these 25.80 - <quote>ifdefs</quote> are not allowed in the Linux kernel 25.81 - tree, a manual or automatic process must be followed to strip 25.82 - them out and yield a clean tree. A code base maintained in 25.83 - this fashion rapidly becomes a rat's nest of conditional 25.84 - blocks that are difficult to understand and maintain.</para> 25.85 - 25.86 - <para id="x_168">Neither of these approaches is well suited to a situation 25.87 - where you don't <quote>own</quote> the canonical copy of a 25.88 - source tree. In the case of a Linux driver that is 25.89 - distributed with the standard kernel, Linus's tree contains 25.90 - the copy of the code that will be treated by the world as 25.91 - canonical. The upstream version of <quote>my</quote> driver 25.92 - can be modified by people I don't know, without me even 25.93 - finding out about it until after the changes show up in 25.94 - Linus's tree.</para> 25.95 - 25.96 - <para id="x_169">These approaches have the added weakness of making it 25.97 - difficult to generate well-formed patches to submit 25.98 - upstream.</para> 25.99 - 25.100 - <para id="x_16a">In principle, Mercurial Queues seems like a good candidate 25.101 - to manage a development scenario such as the above. While 25.102 - this is indeed the case, MQ contains a few added features that 25.103 - make the job more pleasant.</para> 25.104 - 25.105 - </sect2> 25.106 - </sect1> 25.107 - <sect1> 25.108 - <title>Conditionally applying patches with guards</title> 25.109 - 25.110 - <para id="x_16b">Perhaps the best way to maintain sanity with so many targets 25.111 - is to be able to choose specific patches to apply for a given 25.112 - situation. MQ provides a feature called <quote>guards</quote> 25.113 - (which originates with quilt's <literal>guards</literal> 25.114 - command) that does just this. To start off, let's create a 25.115 - simple repository for experimenting in.</para> 25.116 - 25.117 - &interaction.mq.guards.init; 25.118 - 25.119 - <para id="x_16c">This gives us a tiny repository that contains two patches 25.120 - that don't have any dependencies on each other, because they 25.121 - touch different files.</para> 25.122 - 25.123 - <para id="x_16d">The idea behind conditional application is that you can 25.124 - <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, 25.125 - which is simply a text string of your choosing, then tell MQ to 25.126 - select specific guards to use when applying patches. MQ will 25.127 - then either apply, or skip over, a guarded patch, depending on 25.128 - the guards that you have selected.</para> 25.129 - 25.130 - <para id="x_16e">A patch can have an arbitrary number of guards; each one is 25.131 - <emphasis>positive</emphasis> (<quote>apply this patch if this 25.132 - guard is selected</quote>) or <emphasis>negative</emphasis> 25.133 - (<quote>skip this patch if this guard is selected</quote>). A 25.134 - patch with no guards is always applied.</para> 25.135 - 25.136 - </sect1> 25.137 - <sect1> 25.138 - <title>Controlling the guards on a patch</title> 25.139 - 25.140 - <para id="x_16f">The <command role="hg-ext-mq">qguard</command> command lets 25.141 - you determine which guards should apply to a patch, or display 25.142 - the guards that are already in effect. Without any arguments, it 25.143 - displays the guards on the current topmost patch.</para> 25.144 - 25.145 - &interaction.mq.guards.qguard; 25.146 - 25.147 - <para id="x_170">To set a positive guard on a patch, prefix the name of the 25.148 - guard with a <quote><literal>+</literal></quote>.</para> 25.149 - 25.150 - &interaction.mq.guards.qguard.pos; 25.151 - 25.152 - <para id="x_171">To set a negative guard 25.153 - on a patch, prefix the name of the guard with a 25.154 - <quote><literal>-</literal></quote>.</para> 25.155 - 25.156 - &interaction.mq.guards.qguard.neg; 25.157 - 25.158 - <note> 25.159 - <para id="x_172"> The <command role="hg-ext-mq">qguard</command> command 25.160 - <emphasis>sets</emphasis> the guards on a patch; it doesn't 25.161 - <emphasis>modify</emphasis> them. What this means is that if 25.162 - you run <command role="hg-cmd">hg qguard +a +b</command> on a 25.163 - patch, then <command role="hg-cmd">hg qguard +c</command> on 25.164 - the same patch, the <emphasis>only</emphasis> guard that will 25.165 - be set on it afterwards is <literal>+c</literal>.</para> 25.166 - </note> 25.167 - 25.168 - <para id="x_173">Mercurial stores guards in the <filename 25.169 - role="special">series</filename> file; the form in which they 25.170 - are stored is easy both to understand and to edit by hand. (In 25.171 - other words, you don't have to use the <command 25.172 - role="hg-ext-mq">qguard</command> command if you don't want 25.173 - to; it's okay to simply edit the <filename 25.174 - role="special">series</filename> file.)</para> 25.175 - 25.176 - &interaction.mq.guards.series; 25.177 - 25.178 - </sect1> 25.179 - <sect1> 25.180 - <title>Selecting the guards to use</title> 25.181 - 25.182 - <para id="x_174">The <command role="hg-ext-mq">qselect</command> command 25.183 - determines which guards are active at a given time. The effect 25.184 - of this is to determine which patches MQ will apply the next 25.185 - time you run <command role="hg-ext-mq">qpush</command>. It has 25.186 - no other effect; in particular, it doesn't do anything to 25.187 - patches that are already applied.</para> 25.188 - 25.189 - <para id="x_175">With no arguments, the <command 25.190 - role="hg-ext-mq">qselect</command> command lists the guards 25.191 - currently in effect, one per line of output. Each argument is 25.192 - treated as the name of a guard to apply.</para> 25.193 - 25.194 - &interaction.mq.guards.qselect.foo; 25.195 - 25.196 - <para id="x_176">In case you're interested, the currently selected guards are 25.197 - stored in the <filename role="special">guards</filename> file.</para> 25.198 - 25.199 - &interaction.mq.guards.qselect.cat; 25.200 - 25.201 - <para id="x_177">We can see the effect the selected guards have when we run 25.202 - <command role="hg-ext-mq">qpush</command>.</para> 25.203 - 25.204 - &interaction.mq.guards.qselect.qpush; 25.205 - 25.206 - <para id="x_178">A guard cannot start with a 25.207 - <quote><literal>+</literal></quote> or 25.208 - <quote><literal>-</literal></quote> character. The name of a 25.209 - guard must not contain white space, but most other characters 25.210 - are acceptable. If you try to use a guard with an invalid name, 25.211 - MQ will complain:</para> 25.212 - 25.213 - &interaction.mq.guards.qselect.error; 25.214 - 25.215 - <para id="x_179">Changing the selected guards changes the patches that are 25.216 - applied.</para> 25.217 - 25.218 - &interaction.mq.guards.qselect.quux; 25.219 - 25.220 - <para id="x_17a">You can see in the example below that negative guards take 25.221 - precedence over positive guards.</para> 25.222 - 25.223 - &interaction.mq.guards.qselect.foobar; 25.224 - 25.225 - </sect1> 25.226 - <sect1> 25.227 - <title>MQ's rules for applying patches</title> 25.228 - 25.229 - <para id="x_17b">The rules that MQ uses when deciding whether to apply a 25.230 - patch are as follows.</para> 25.231 - <itemizedlist> 25.232 - <listitem><para id="x_17c">A patch that has no guards is always 25.233 - applied.</para> 25.234 - </listitem> 25.235 - <listitem><para id="x_17d">If the patch has any negative guard that matches 25.236 - any currently selected guard, the patch is skipped.</para> 25.237 - </listitem> 25.238 - <listitem><para id="x_17e">If the patch has any positive guard that matches 25.239 - any currently selected guard, the patch is applied.</para> 25.240 - </listitem> 25.241 - <listitem><para id="x_17f">If the patch has positive or negative guards, 25.242 - but none matches any currently selected guard, the patch is 25.243 - skipped.</para> 25.244 - </listitem></itemizedlist> 25.245 - 25.246 - </sect1> 25.247 - <sect1> 25.248 - <title>Trimming the work environment</title> 25.249 - 25.250 - <para id="x_180">In working on the device driver I mentioned earlier, I don't 25.251 - apply the patches to a normal Linux kernel tree. Instead, I use 25.252 - a repository that contains only a snapshot of the source files 25.253 - and headers that are relevant to Infiniband development. This 25.254 - repository is 1% the size of a kernel repository, so it's easier 25.255 - to work with.</para> 25.256 - 25.257 - <para id="x_181">I then choose a <quote>base</quote> version on top of which 25.258 - the patches are applied. This is a snapshot of the Linux kernel 25.259 - tree as of a revision of my choosing. When I take the snapshot, 25.260 - I record the changeset ID from the kernel repository in the 25.261 - commit message. Since the snapshot preserves the 25.262 - <quote>shape</quote> and content of the relevant parts of the 25.263 - kernel tree, I can apply my patches on top of either my tiny 25.264 - repository or a normal kernel tree.</para> 25.265 - 25.266 - <para id="x_182">Normally, the base tree atop which the patches apply should 25.267 - be a snapshot of a very recent upstream tree. This best 25.268 - facilitates the development of patches that can easily be 25.269 - submitted upstream with few or no modifications.</para> 25.270 - 25.271 - </sect1> 25.272 - <sect1> 25.273 - <title>Dividing up the <filename role="special">series</filename> 25.274 - file</title> 25.275 - 25.276 - <para id="x_183">I categorise the patches in the <filename 25.277 - role="special">series</filename> file into a number of logical 25.278 - groups. Each section of like patches begins with a block of 25.279 - comments that describes the purpose of the patches that 25.280 - follow.</para> 25.281 - 25.282 - <para id="x_184">The sequence of patch groups that I maintain follows. The 25.283 - ordering of these groups is important; I'll describe why after I 25.284 - introduce the groups.</para> 25.285 - <itemizedlist> 25.286 - <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that 25.287 - the development team has submitted to the maintainer of the 25.288 - Infiniband subsystem, and which he has accepted, but which 25.289 - are not present in the snapshot that the tiny repository is 25.290 - based on. These are <quote>read only</quote> patches, 25.291 - present only to transform the tree into a similar state as 25.292 - it is in the upstream maintainer's repository.</para> 25.293 - </listitem> 25.294 - <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I 25.295 - have submitted, but that the upstream maintainer has 25.296 - requested modifications to before he will accept 25.297 - them.</para> 25.298 - </listitem> 25.299 - <listitem><para id="x_187">The <quote>pending</quote> group. Patches that 25.300 - I have not yet submitted to the upstream maintainer, but 25.301 - which we have finished working on. These will be <quote>read 25.302 - only</quote> for a while. If the upstream maintainer 25.303 - accepts them upon submission, I'll move them to the end of 25.304 - the <quote>accepted</quote> group. If he requests that I 25.305 - modify any, I'll move them to the beginning of the 25.306 - <quote>rework</quote> group.</para> 25.307 - </listitem> 25.308 - <listitem><para id="x_188">The <quote>in progress</quote> group. Patches 25.309 - that are actively being developed, and should not be 25.310 - submitted anywhere yet.</para> 25.311 - </listitem> 25.312 - <listitem><para id="x_189">The <quote>backport</quote> group. Patches that 25.313 - adapt the source tree to older versions of the kernel 25.314 - tree.</para> 25.315 - </listitem> 25.316 - <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches 25.317 - that for some reason should never be submitted upstream. 25.318 - For example, one such patch might change embedded driver 25.319 - identification strings to make it easier to distinguish, in 25.320 - the field, between an out-of-tree version of the driver and 25.321 - a version shipped by a distribution vendor.</para> 25.322 - </listitem></itemizedlist> 25.323 - 25.324 - <para id="x_18b">Now to return to the reasons for ordering groups of patches 25.325 - in this way. We would like the lowest patches in the stack to 25.326 - be as stable as possible, so that we will not need to rework 25.327 - higher patches due to changes in context. Putting patches that 25.328 - will never be changed first in the <filename 25.329 - role="special">series</filename> file serves this 25.330 - purpose.</para> 25.331 - 25.332 - <para id="x_18c">We would also like the patches that we know we'll need to 25.333 - modify to be applied on top of a source tree that resembles the 25.334 - upstream tree as closely as possible. This is why we keep 25.335 - accepted patches around for a while.</para> 25.336 - 25.337 - <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote> 25.338 - patches float at the end of the <filename 25.339 - role="special">series</filename> file. The backport patches 25.340 - must be applied on top of all other patches, and the <quote>do 25.341 - not ship</quote> patches might as well stay out of harm's 25.342 - way.</para> 25.343 - 25.344 - </sect1> 25.345 - <sect1> 25.346 - <title>Maintaining the patch series</title> 25.347 - 25.348 - <para id="x_18e">In my work, I use a number of guards to control which 25.349 - patches are to be applied.</para> 25.350 - 25.351 - <itemizedlist> 25.352 - <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with 25.353 - <literal>accepted</literal>. I enable this guard most of 25.354 - the time. When I'm applying the patches on top of a tree 25.355 - where the patches are already present, I can turn this patch 25.356 - off, and the patches that follow it will apply 25.357 - cleanly.</para> 25.358 - </listitem> 25.359 - <listitem><para id="x_190">Patches that are <quote>finished</quote>, but 25.360 - not yet submitted, have no guards. If I'm applying the 25.361 - patch stack to a copy of the upstream tree, I don't need to 25.362 - enable any guards in order to get a reasonably safe source 25.363 - tree.</para> 25.364 - </listitem> 25.365 - <listitem><para id="x_191">Those patches that need reworking before being 25.366 - resubmitted are guarded with 25.367 - <literal>rework</literal>.</para> 25.368 - </listitem> 25.369 - <listitem><para id="x_192">For those patches that are still under 25.370 - development, I use <literal>devel</literal>.</para> 25.371 - </listitem> 25.372 - <listitem><para id="x_193">A backport patch may have several guards, one 25.373 - for each version of the kernel to which it applies. For 25.374 - example, a patch that backports a piece of code to 2.6.9 25.375 - will have a <literal>2.6.9</literal> guard.</para> 25.376 - </listitem></itemizedlist> 25.377 - <para id="x_194">This variety of guards gives me considerable flexibility in 25.378 - determining what kind of source tree I want to end up with. For 25.379 - most situations, the selection of appropriate guards is 25.380 - automated during the build process, but I can manually tune the 25.381 - guards to use for less common circumstances.</para> 25.382 - 25.383 - <sect2> 25.384 - <title>The art of writing backport patches</title> 25.385 - 25.386 - <para id="x_195">Using MQ, writing a backport patch is a simple process. 25.387 - All such a patch has to do is modify a piece of code that uses 25.388 - a kernel feature not present in the older version of the 25.389 - kernel, so that the driver continues to work correctly under 25.390 - that older version.</para> 25.391 - 25.392 - <para id="x_196">A useful goal when writing a good backport patch is to 25.393 - make your code look as if it was written for the older version 25.394 - of the kernel you're targeting. The less obtrusive the patch, 25.395 - the easier it will be to understand and maintain. If you're 25.396 - writing a collection of backport patches to avoid the 25.397 - <quote>rat's nest</quote> effect of lots of 25.398 - <literal>#ifdef</literal>s (hunks of source code that are only 25.399 - used conditionally) in your code, don't introduce 25.400 - version-dependent <literal>#ifdef</literal>s into the patches. 25.401 - Instead, write several patches, each of which makes 25.402 - unconditional changes, and control their application using 25.403 - guards.</para> 25.404 - 25.405 - <para id="x_197">There are two reasons to divide backport patches into a 25.406 - distinct group, away from the <quote>regular</quote> patches 25.407 - whose effects they modify. The first is that intermingling the 25.408 - two makes it more difficult to use a tool like the <literal 25.409 - role="hg-ext">patchbomb</literal> extension to automate the 25.410 - process of submitting the patches to an upstream maintainer. 25.411 - The second is that a backport patch could perturb the context 25.412 - in which a subsequent regular patch is applied, making it 25.413 - impossible to apply the regular patch cleanly 25.414 - <emphasis>without</emphasis> the earlier backport patch 25.415 - already being applied.</para> 25.416 - 25.417 - </sect2> 25.418 - </sect1> 25.419 - <sect1> 25.420 - <title>Useful tips for developing with MQ</title> 25.421 - 25.422 - <sect2> 25.423 - <title>Organising patches in directories</title> 25.424 - 25.425 - <para id="x_198">If you're working on a substantial project with MQ, it's 25.426 - not difficult to accumulate a large number of patches. For 25.427 - example, I have one patch repository that contains over 250 25.428 - patches.</para> 25.429 - 25.430 - <para id="x_199">If you can group these patches into separate logical 25.431 - categories, you can if you like store them in different 25.432 - directories; MQ has no problems with patch names that contain 25.433 - path separators.</para> 25.434 - 25.435 - </sect2> 25.436 - <sect2 id="mq-collab:tips:interdiff"> 25.437 - <title>Viewing the history of a patch</title> 25.438 - 25.439 - <para id="x_19a">If you're developing a set of patches over a long time, 25.440 - it's a good idea to maintain them in a repository, as 25.441 - discussed in <xref linkend="sec:mq:repo"/>. If you do 25.442 - so, you'll quickly 25.443 - discover that using the <command role="hg-cmd">hg 25.444 - diff</command> command to look at the history of changes to 25.445 - a patch is unworkable. This is in part because you're looking 25.446 - at the second derivative of the real code (a diff of a diff), 25.447 - but also because MQ adds noise to the process by modifying 25.448 - time stamps and directory names when it updates a 25.449 - patch.</para> 25.450 - 25.451 - <para id="x_19b">However, you can use the <literal 25.452 - role="hg-ext">extdiff</literal> extension, which is bundled 25.453 - with Mercurial, to turn a diff of two versions of a patch into 25.454 - something readable. To do this, you will need a third-party 25.455 - package called <literal role="package">patchutils</literal> 25.456 - <citation>web:patchutils</citation>. This provides a command 25.457 - named <command>interdiff</command>, which shows the 25.458 - differences between two diffs as a diff. Used on two versions 25.459 - of the same diff, it generates a diff that represents the diff 25.460 - from the first to the second version.</para> 25.461 - 25.462 - <para id="x_19c">You can enable the <literal 25.463 - role="hg-ext">extdiff</literal> extension in the usual way, 25.464 - by adding a line to the <literal 25.465 - role="rc-extensions">extensions</literal> section of your 25.466 - <filename role="special">~/.hgrc</filename>.</para> 25.467 - <programlisting>[extensions] 25.468 -extdiff =</programlisting> 25.469 - <para id="x_19d">The <command>interdiff</command> command expects to be 25.470 - passed the names of two files, but the <literal 25.471 - role="hg-ext">extdiff</literal> extension passes the program 25.472 - it runs a pair of directories, each of which can contain an 25.473 - arbitrary number of files. We thus need a small program that 25.474 - will run <command>interdiff</command> on each pair of files in 25.475 - these two directories. This program is available as <filename 25.476 - role="special">hg-interdiff</filename> in the <filename 25.477 - class="directory">examples</filename> directory of the 25.478 - source code repository that accompanies this book. <!-- 25.479 - &example.hg-interdiff; --></para> 25.480 - 25.481 - <para id="x_19e">With the <filename role="special">hg-interdiff</filename> 25.482 - program in your shell's search path, you can run it as 25.483 - follows, from inside an MQ patch directory:</para> 25.484 - <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting> 25.485 - <para id="x_19f">Since you'll probably want to use this long-winded command 25.486 - a lot, you can get <literal role="hg-ext">hgext</literal> to 25.487 - make it available as a normal Mercurial command, again by 25.488 - editing your <filename 25.489 - role="special">~/.hgrc</filename>.</para> 25.490 - <programlisting>[extdiff] 25.491 -cmd.interdiff = hg-interdiff</programlisting> 25.492 - <para id="x_1a0">This directs <literal role="hg-ext">hgext</literal> to 25.493 - make an <literal>interdiff</literal> command available, so you 25.494 - can now shorten the previous invocation of <command 25.495 - role="hg-ext-extdiff">extdiff</command> to something a 25.496 - little more wieldy.</para> 25.497 - <programlisting>hg interdiff -r A:B my-change.patch</programlisting> 25.498 - 25.499 - <note> 25.500 - <para id="x_1a1"> The <command>interdiff</command> command works well 25.501 - only if the underlying files against which versions of a 25.502 - patch are generated remain the same. If you create a patch, 25.503 - modify the underlying files, and then regenerate the patch, 25.504 - <command>interdiff</command> may not produce useful 25.505 - output.</para> 25.506 - </note> 25.507 - 25.508 - <para id="x_1a2">The <literal role="hg-ext">extdiff</literal> extension is 25.509 - useful for more than merely improving the presentation of MQ 25.510 - patches. To read more about it, go to <xref 25.511 - linkend="sec:hgext:extdiff"/>.</para> 25.512 - 25.513 - </sect2> 25.514 - </sect1> 25.515 -</chapter> 25.516 - 25.517 -<!-- 25.518 -local variables: 25.519 -sgml-parent-document: ("00book.xml" "book" "chapter") 25.520 -end: 25.521 --->
26.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 26.2 +++ b/en/ch12-mq.xml Thu May 07 21:07:35 2009 -0700 26.3 @@ -0,0 +1,1368 @@ 26.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 26.5 + 26.6 +<chapter id="chap:mq"> 26.7 + <?dbhtml filename="managing-change-with-mercurial-queues.html"?> 26.8 + <title>Managing change with Mercurial Queues</title> 26.9 + 26.10 + <sect1 id="sec:mq:patch-mgmt"> 26.11 + <title>The patch management problem</title> 26.12 + 26.13 + <para id="x_3ac">Here is a common scenario: you need to install a software 26.14 + package from source, but you find a bug that you must fix in the 26.15 + source before you can start using the package. You make your 26.16 + changes, forget about the package for a while, and a few months 26.17 + later you need to upgrade to a newer version of the package. If 26.18 + the newer version of the package still has the bug, you must 26.19 + extract your fix from the older source tree and apply it against 26.20 + the newer version. This is a tedious task, and it's easy to 26.21 + make mistakes.</para> 26.22 + 26.23 + <para id="x_3ad">This is a simple case of the <quote>patch management</quote> 26.24 + problem. You have an <quote>upstream</quote> source tree that 26.25 + you can't change; you need to make some local changes on top of 26.26 + the upstream tree; and you'd like to be able to keep those 26.27 + changes separate, so that you can apply them to newer versions 26.28 + of the upstream source.</para> 26.29 + 26.30 + <para id="x_3ae">The patch management problem arises in many situations. 26.31 + Probably the most visible is that a user of an open source 26.32 + software project will contribute a bug fix or new feature to the 26.33 + project's maintainers in the form of a patch.</para> 26.34 + 26.35 + <para id="x_3af">Distributors of operating systems that include open source 26.36 + software often need to make changes to the packages they 26.37 + distribute so that they will build properly in their 26.38 + environments.</para> 26.39 + 26.40 + <para id="x_3b0">When you have few changes to maintain, it is easy to manage 26.41 + a single patch using the standard <command>diff</command> and 26.42 + <command>patch</command> programs (see <xref 26.43 + linkend="sec:mq:patch"/> for a discussion of these 26.44 + tools). Once the number of changes grows, it starts to make 26.45 + sense to maintain patches as discrete <quote>chunks of 26.46 + work,</quote> so that for example a single patch will contain 26.47 + only one bug fix (the patch might modify several files, but it's 26.48 + doing <quote>only one thing</quote>), and you may have a number 26.49 + of such patches for different bugs you need fixed and local 26.50 + changes you require. In this situation, if you submit a bug fix 26.51 + patch to the upstream maintainers of a package and they include 26.52 + your fix in a subsequent release, you can simply drop that 26.53 + single patch when you're updating to the newer release.</para> 26.54 + 26.55 + <para id="x_3b1">Maintaining a single patch against an upstream tree is a 26.56 + little tedious and error-prone, but not difficult. However, the 26.57 + complexity of the problem grows rapidly as the number of patches 26.58 + you have to maintain increases. With more than a tiny number of 26.59 + patches in hand, understanding which ones you have applied and 26.60 + maintaining them moves from messy to overwhelming.</para> 26.61 + 26.62 + <para id="x_3b2">Fortunately, Mercurial includes a powerful extension, 26.63 + Mercurial Queues (or simply <quote>MQ</quote>), that massively 26.64 + simplifies the patch management problem.</para> 26.65 + 26.66 + </sect1> 26.67 + <sect1 id="sec:mq:history"> 26.68 + <title>The prehistory of Mercurial Queues</title> 26.69 + 26.70 + <para id="x_3b3">During the late 1990s, several Linux kernel developers 26.71 + started to maintain <quote>patch series</quote> that modified 26.72 + the behavior of the Linux kernel. Some of these series were 26.73 + focused on stability, some on feature coverage, and others were 26.74 + more speculative.</para> 26.75 + 26.76 + <para id="x_3b4">The sizes of these patch series grew rapidly. In 2002, 26.77 + Andrew Morton published some shell scripts he had been using to 26.78 + automate the task of managing his patch queues. Andrew was 26.79 + successfully using these scripts to manage hundreds (sometimes 26.80 + thousands) of patches on top of the Linux kernel.</para> 26.81 + 26.82 + <sect2 id="sec:mq:quilt"> 26.83 + <title>A patchwork quilt</title> 26.84 + 26.85 + <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson 26.86 + borrowed the approach of Andrew's scripts and published a tool 26.87 + called <quote>patchwork quilt</quote> 26.88 + <citation>web:quilt</citation>, or simply <quote>quilt</quote> 26.89 + (see <citation>gruenbacher:2005</citation> for a paper 26.90 + describing it). Because quilt substantially automated patch 26.91 + management, it rapidly gained a large following among open 26.92 + source software developers.</para> 26.93 + 26.94 + <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on 26.95 + top of a directory tree. To begin, you tell quilt to manage a 26.96 + directory tree, and tell it which files you want to manage; it 26.97 + stores away the names and contents of those files. To fix a 26.98 + bug, you create a new patch (using a single command), edit the 26.99 + files you need to fix, then <quote>refresh</quote> the 26.100 + patch.</para> 26.101 + 26.102 + <para id="x_3b7">The refresh step causes quilt to scan the directory tree; 26.103 + it updates the patch with all of the changes you have made. 26.104 + You can create another patch on top of the first, which will 26.105 + track the changes required to modify the tree from <quote>tree 26.106 + with one patch applied</quote> to <quote>tree with two 26.107 + patches applied</quote>.</para> 26.108 + 26.109 + <para id="x_3b8">You can <emphasis>change</emphasis> which patches are 26.110 + applied to the tree. If you <quote>pop</quote> a patch, the 26.111 + changes made by that patch will vanish from the directory 26.112 + tree. Quilt remembers which patches you have popped, though, 26.113 + so you can <quote>push</quote> a popped patch again, and the 26.114 + directory tree will be restored to contain the modifications 26.115 + in the patch. Most importantly, you can run the 26.116 + <quote>refresh</quote> command at any time, and the topmost 26.117 + applied patch will be updated. This means that you can, at 26.118 + any time, change both which patches are applied and what 26.119 + modifications those patches make.</para> 26.120 + 26.121 + <para id="x_3b9">Quilt knows nothing about revision control tools, so it 26.122 + works equally well on top of an unpacked tarball or a 26.123 + Subversion working copy.</para> 26.124 + </sect2> 26.125 + 26.126 + <sect2 id="sec:mq:quilt-mq"> 26.127 + <title>From patchwork quilt to Mercurial Queues</title> 26.128 + 26.129 + <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and 26.130 + wrote an extension that he called Mercurial Queues, which 26.131 + added quilt-like behavior to Mercurial.</para> 26.132 + 26.133 + <para id="x_3bb">The key difference between quilt and MQ is that quilt 26.134 + knows nothing about revision control systems, while MQ is 26.135 + <emphasis>integrated</emphasis> into Mercurial. Each patch 26.136 + that you push is represented as a Mercurial changeset. Pop a 26.137 + patch, and the changeset goes away.</para> 26.138 + 26.139 + <para id="x_3bc">Because quilt does not care about revision control tools, 26.140 + it is still a tremendously useful piece of software to know 26.141 + about for situations where you cannot use Mercurial and 26.142 + MQ.</para> 26.143 + 26.144 + </sect2> 26.145 + </sect1> 26.146 + <sect1> 26.147 + <title>The huge advantage of MQ</title> 26.148 + 26.149 + <para id="x_3bd">I cannot overstate the value that MQ offers through the 26.150 + unification of patches and revision control.</para> 26.151 + 26.152 + <para id="x_3be">A major reason that patches have persisted in the free 26.153 + software and open source world&emdash;in spite of the 26.154 + availability of increasingly capable revision control tools over 26.155 + the years&emdash;is the <emphasis>agility</emphasis> they 26.156 + offer.</para> 26.157 + 26.158 + <para id="x_3bf">Traditional revision control tools make a permanent, 26.159 + irreversible record of everything that you do. While this has 26.160 + great value, it's also somewhat stifling. If you want to 26.161 + perform a wild-eyed experiment, you have to be careful in how 26.162 + you go about it, or you risk leaving unneeded&emdash;or worse, 26.163 + misleading or destabilising&emdash;traces of your missteps and 26.164 + errors in the permanent revision record.</para> 26.165 + 26.166 + <para id="x_3c0">By contrast, MQ's marriage of distributed revision control 26.167 + with patches makes it much easier to isolate your work. Your 26.168 + patches live on top of normal revision history, and you can make 26.169 + them disappear or reappear at will. If you don't like a patch, 26.170 + you can drop it. If a patch isn't quite as you want it to be, 26.171 + simply fix it&emdash;as many times as you need to, until you 26.172 + have refined it into the form you desire.</para> 26.173 + 26.174 + <para id="x_3c1">As an example, the integration of patches with revision 26.175 + control makes understanding patches and debugging their 26.176 + effects&emdash;and their interplay with the code they're based 26.177 + on&emdash;<emphasis>enormously</emphasis> easier. Since every 26.178 + applied patch has an associated changeset, you can give <command 26.179 + role="hg-cmd">hg log</command> a file name to see which 26.180 + changesets and patches affected the file. You can use the 26.181 + <command role="hg-cmd">hg bisect</command> command to 26.182 + binary-search through all changesets and applied patches to see 26.183 + where a bug got introduced or fixed. You can use the <command 26.184 + role="hg-cmd">hg annotate</command> command to see which 26.185 + changeset or patch modified a particular line of a source file. 26.186 + And so on.</para> 26.187 + </sect1> 26.188 + 26.189 + <sect1 id="sec:mq:patch"> 26.190 + <title>Understanding patches</title> 26.191 + 26.192 + <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is 26.193 + helpful to understand what patches are, and a little about the 26.194 + tools that work with them.</para> 26.195 + 26.196 + <para id="x_3c3">The traditional Unix <command>diff</command> command 26.197 + compares two files, and prints a list of differences between 26.198 + them. The <command>patch</command> command understands these 26.199 + differences as <emphasis>modifications</emphasis> to make to a 26.200 + file. Take a look below for a simple example of these commands 26.201 + in action.</para> 26.202 + 26.203 + &interaction.mq.dodiff.diff; 26.204 + 26.205 + <para id="x_3c4">The type of file that <command>diff</command> generates (and 26.206 + <command>patch</command> takes as input) is called a 26.207 + <quote>patch</quote> or a <quote>diff</quote>; there is no 26.208 + difference between a patch and a diff. (We'll use the term 26.209 + <quote>patch</quote>, since it's more commonly used.)</para> 26.210 + 26.211 + <para id="x_3c5">A patch file can start with arbitrary text; the 26.212 + <command>patch</command> command ignores this text, but MQ uses 26.213 + it as the commit message when creating changesets. To find the 26.214 + beginning of the patch content, <command>patch</command> 26.215 + searches for the first line that starts with the string 26.216 + <quote><literal>diff -</literal></quote>.</para> 26.217 + 26.218 + <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs 26.219 + (<command>patch</command> can accept several other diff formats, 26.220 + but MQ doesn't). A unified diff contains two kinds of header. 26.221 + The <emphasis>file header</emphasis> describes the file being 26.222 + modified; it contains the name of the file to modify. When 26.223 + <command>patch</command> sees a new file header, it looks for a 26.224 + file with that name to start modifying.</para> 26.225 + 26.226 + <para id="x_3c7">After the file header comes a series of 26.227 + <emphasis>hunks</emphasis>. Each hunk starts with a header; 26.228 + this identifies the range of line numbers within the file that 26.229 + the hunk should modify. Following the header, a hunk starts and 26.230 + ends with a few (usually three) lines of text from the 26.231 + unmodified file; these are called the 26.232 + <emphasis>context</emphasis> for the hunk. If there's only a 26.233 + small amount of context between successive hunks, 26.234 + <command>diff</command> doesn't print a new hunk header; it just 26.235 + runs the hunks together, with a few lines of context between 26.236 + modifications.</para> 26.237 + 26.238 + <para id="x_3c8">Each line of context begins with a space character. Within 26.239 + the hunk, a line that begins with 26.240 + <quote><literal>-</literal></quote> means <quote>remove this 26.241 + line,</quote> while a line that begins with 26.242 + <quote><literal>+</literal></quote> means <quote>insert this 26.243 + line.</quote> For example, a line that is modified is 26.244 + represented by one deletion and one insertion.</para> 26.245 + 26.246 + <para id="x_3c9">We will return to some of the more subtle aspects of patches 26.247 + later (in <xref linkend="sec:mq:adv-patch"/>), but you 26.248 + should have 26.249 + enough information now to use MQ.</para> 26.250 + </sect1> 26.251 + 26.252 + <sect1 id="sec:mq:start"> 26.253 + <title>Getting started with Mercurial Queues</title> 26.254 + 26.255 + <para id="x_3ca">Because MQ is implemented as an extension, you must 26.256 + explicitly enable before you can use it. (You don't need to 26.257 + download anything; MQ ships with the standard Mercurial 26.258 + distribution.) To enable MQ, edit your <filename 26.259 + role="home">~/.hgrc</filename> file, and add the lines 26.260 + below.</para> 26.261 + 26.262 + <programlisting>[extensions] 26.263 +hgext.mq =</programlisting> 26.264 + 26.265 + <para id="x_3cb">Once the extension is enabled, it will make a number of new 26.266 + commands available. To verify that the extension is working, 26.267 + you can use <command role="hg-cmd">hg help</command> to see if 26.268 + the <command role="hg-ext-mq">qinit</command> command is now 26.269 + available.</para> 26.270 + 26.271 + &interaction.mq.qinit-help.help; 26.272 + 26.273 + <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial 26.274 + repository, and its commands only operate within that 26.275 + repository. To get started, simply prepare the repository using 26.276 + the <command role="hg-ext-mq">qinit</command> command.</para> 26.277 + 26.278 + &interaction.mq.tutorial.qinit; 26.279 + 26.280 + <para id="x_3cd">This command creates an empty directory called <filename 26.281 + role="special" class="directory">.hg/patches</filename>, where 26.282 + MQ will keep its metadata. As with many Mercurial commands, the 26.283 + <command role="hg-ext-mq">qinit</command> command prints nothing 26.284 + if it succeeds.</para> 26.285 + 26.286 + <sect2> 26.287 + <title>Creating a new patch</title> 26.288 + 26.289 + <para id="x_3ce">To begin work on a new patch, use the <command 26.290 + role="hg-ext-mq">qnew</command> command. This command takes 26.291 + one argument, the name of the patch to create.</para> 26.292 + 26.293 + <para id="x_3cf">MQ will use this as the name of an actual file in the 26.294 + <filename role="special" 26.295 + class="directory">.hg/patches</filename> directory, as you 26.296 + can see below.</para> 26.297 + 26.298 + &interaction.mq.tutorial.qnew; 26.299 + 26.300 + <para id="x_3d0">Also newly present in the <filename role="special" 26.301 + class="directory">.hg/patches</filename> directory are two 26.302 + other files, <filename role="special">series</filename> and 26.303 + <filename role="special">status</filename>. The <filename 26.304 + role="special">series</filename> file lists all of the 26.305 + patches that MQ knows about for this repository, with one 26.306 + patch per line. Mercurial uses the <filename 26.307 + role="special">status</filename> file for internal 26.308 + book-keeping; it tracks all of the patches that MQ has 26.309 + <emphasis>applied</emphasis> in this repository.</para> 26.310 + 26.311 + <note> 26.312 + <para id="x_3d1"> You may sometimes want to edit the <filename 26.313 + role="special">series</filename> file by hand; for 26.314 + example, to change the sequence in which some patches are 26.315 + applied. However, manually editing the <filename 26.316 + role="special">status</filename> file is almost always a 26.317 + bad idea, as it's easy to corrupt MQ's idea of what is 26.318 + happening.</para> 26.319 + </note> 26.320 + 26.321 + <para id="x_3d2">Once you have created your new patch, you can edit files 26.322 + in the working directory as you usually would. All of the 26.323 + normal Mercurial commands, such as <command role="hg-cmd">hg 26.324 + diff</command> and <command role="hg-cmd">hg 26.325 + annotate</command>, work exactly as they did before.</para> 26.326 + </sect2> 26.327 + 26.328 + <sect2> 26.329 + <title>Refreshing a patch</title> 26.330 + 26.331 + <para id="x_3d3">When you reach a point where you want to save your work, 26.332 + use the <command role="hg-ext-mq">qrefresh</command> command 26.333 + to update the patch you are working on.</para> 26.334 + 26.335 + &interaction.mq.tutorial.qrefresh; 26.336 + 26.337 + <para id="x_3d4">This command folds the changes you have made in the 26.338 + working directory into your patch, and updates its 26.339 + corresponding changeset to contain those changes.</para> 26.340 + 26.341 + <para id="x_3d5">You can run <command role="hg-ext-mq">qrefresh</command> 26.342 + as often as you like, so it's a good way to 26.343 + <quote>checkpoint</quote> your work. Refresh your patch at an 26.344 + opportune time; try an experiment; and if the experiment 26.345 + doesn't work out, <command role="hg-cmd">hg revert</command> 26.346 + your modifications back to the last time you refreshed.</para> 26.347 + 26.348 + &interaction.mq.tutorial.qrefresh2; 26.349 + </sect2> 26.350 + 26.351 + <sect2> 26.352 + <title>Stacking and tracking patches</title> 26.353 + 26.354 + <para id="x_3d6">Once you have finished working on a patch, or need to work 26.355 + on another, you can use the <command 26.356 + role="hg-ext-mq">qnew</command> command again to create a 26.357 + new patch. Mercurial will apply this patch on top of your 26.358 + existing patch.</para> 26.359 + 26.360 + &interaction.mq.tutorial.qnew2; 26.361 + 26.362 + <para id="x_3d7">Notice that the patch contains the changes in our prior 26.363 + patch as part of its context (you can see this more clearly in 26.364 + the output of <command role="hg-cmd">hg 26.365 + annotate</command>).</para> 26.366 + 26.367 + <para id="x_3d8">So far, with the exception of <command 26.368 + role="hg-ext-mq">qnew</command> and <command 26.369 + role="hg-ext-mq">qrefresh</command>, we've been careful to 26.370 + only use regular Mercurial commands. However, MQ provides 26.371 + many commands that are easier to use when you are thinking 26.372 + about patches, as illustrated below.</para> 26.373 + 26.374 + &interaction.mq.tutorial.qseries; 26.375 + 26.376 + <itemizedlist> 26.377 + <listitem><para id="x_3d9">The <command 26.378 + role="hg-ext-mq">qseries</command> command lists every 26.379 + patch that MQ knows about in this repository, from oldest 26.380 + to newest (most recently 26.381 + <emphasis>created</emphasis>).</para> 26.382 + </listitem> 26.383 + <listitem><para id="x_3da">The <command 26.384 + role="hg-ext-mq">qapplied</command> command lists every 26.385 + patch that MQ has <emphasis>applied</emphasis> in this 26.386 + repository, again from oldest to newest (most recently 26.387 + applied).</para> 26.388 + </listitem></itemizedlist> 26.389 + </sect2> 26.390 + 26.391 + <sect2> 26.392 + <title>Manipulating the patch stack</title> 26.393 + 26.394 + <para id="x_3db">The previous discussion implied that there must be a 26.395 + difference between <quote>known</quote> and 26.396 + <quote>applied</quote> patches, and there is. MQ can manage a 26.397 + patch without it being applied in the repository.</para> 26.398 + 26.399 + <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding 26.400 + changeset in the repository, and the effects of the patch and 26.401 + changeset are visible in the working directory. You can undo 26.402 + the application of a patch using the <command 26.403 + role="hg-ext-mq">qpop</command> command. MQ still 26.404 + <emphasis>knows about</emphasis>, or manages, a popped patch, 26.405 + but the patch no longer has a corresponding changeset in the 26.406 + repository, and the working directory does not contain the 26.407 + changes made by the patch. <xref 26.408 + linkend="fig:mq:stack"/> illustrates 26.409 + the difference between applied and tracked patches.</para> 26.410 + 26.411 + <figure id="fig:mq:stack"> 26.412 + <title>Applied and unapplied patches in the MQ patch 26.413 + stack</title> 26.414 + <mediaobject> 26.415 + <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject> 26.416 + <textobject><phrase>XXX add text</phrase></textobject> 26.417 + </mediaobject> 26.418 + </figure> 26.419 + 26.420 + <para id="x_3de">You can reapply an unapplied, or popped, patch using the 26.421 + <command role="hg-ext-mq">qpush</command> command. This 26.422 + creates a new changeset to correspond to the patch, and the 26.423 + patch's changes once again become present in the working 26.424 + directory. See below for examples of <command 26.425 + role="hg-ext-mq">qpop</command> and <command 26.426 + role="hg-ext-mq">qpush</command> in action.</para> 26.427 + 26.428 + &interaction.mq.tutorial.qpop; 26.429 + 26.430 + <para id="x_3df">Notice that once we have popped a patch or two patches, 26.431 + the output of <command role="hg-ext-mq">qseries</command> 26.432 + remains the same, while that of <command 26.433 + role="hg-ext-mq">qapplied</command> has changed.</para> 26.434 + 26.435 + </sect2> 26.436 + 26.437 + <sect2> 26.438 + <title>Pushing and popping many patches</title> 26.439 + 26.440 + <para id="x_3e0">While <command role="hg-ext-mq">qpush</command> and 26.441 + <command role="hg-ext-mq">qpop</command> each operate on a 26.442 + single patch at a time by default, you can push and pop many 26.443 + patches in one go. The <option 26.444 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to 26.445 + <command role="hg-ext-mq">qpush</command> causes it to push 26.446 + all unapplied patches, while the <option 26.447 + role="hg-ext-mq-cmd-qpop-opt">-a</option> option to <command 26.448 + role="hg-ext-mq">qpop</command> causes it to pop all applied 26.449 + patches. (For some more ways to push and pop many patches, 26.450 + see <xref linkend="sec:mq:perf"/> below.)</para> 26.451 + 26.452 + &interaction.mq.tutorial.qpush-a; 26.453 + </sect2> 26.454 + 26.455 + <sect2> 26.456 + <title>Safety checks, and overriding them</title> 26.457 + 26.458 + <para id="x_3e1">Several MQ commands check the working directory before 26.459 + they do anything, and fail if they find any modifications. 26.460 + They do this to ensure that you won't lose any changes that 26.461 + you have made, but not yet incorporated into a patch. The 26.462 + example below illustrates this; the <command 26.463 + role="hg-ext-mq">qnew</command> command will not create a 26.464 + new patch if there are outstanding changes, caused in this 26.465 + case by the <command role="hg-cmd">hg add</command> of 26.466 + <filename>file3</filename>.</para> 26.467 + 26.468 + &interaction.mq.tutorial.add; 26.469 + 26.470 + <para id="x_3e2">Commands that check the working directory all take an 26.471 + <quote>I know what I'm doing</quote> option, which is always 26.472 + named <option>-f</option>. The exact meaning of 26.473 + <option>-f</option> depends on the command. For example, 26.474 + <command role="hg-cmd">hg qnew <option 26.475 + role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command> 26.476 + will incorporate any outstanding changes into the new patch it 26.477 + creates, but <command role="hg-cmd">hg qpop <option 26.478 + role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command> 26.479 + will revert modifications to any files affected by the patch 26.480 + that it is popping. Be sure to read the documentation for a 26.481 + command's <option>-f</option> option before you use it!</para> 26.482 + </sect2> 26.483 + 26.484 + <sect2> 26.485 + <title>Working on several patches at once</title> 26.486 + 26.487 + <para id="x_3e3">The <command role="hg-ext-mq">qrefresh</command> command 26.488 + always refreshes the <emphasis>topmost</emphasis> applied 26.489 + patch. This means that you can suspend work on one patch (by 26.490 + refreshing it), pop or push to make a different patch the top, 26.491 + and work on <emphasis>that</emphasis> patch for a 26.492 + while.</para> 26.493 + 26.494 + <para id="x_3e4">Here's an example that illustrates how you can use this 26.495 + ability. Let's say you're developing a new feature as two 26.496 + patches. The first is a change to the core of your software, 26.497 + and the second&emdash;layered on top of the 26.498 + first&emdash;changes the user interface to use the code you 26.499 + just added to the core. If you notice a bug in the core while 26.500 + you're working on the UI patch, it's easy to fix the core. 26.501 + Simply <command role="hg-ext-mq">qrefresh</command> the UI 26.502 + patch to save your in-progress changes, and <command 26.503 + role="hg-ext-mq">qpop</command> down to the core patch. Fix 26.504 + the core bug, <command role="hg-ext-mq">qrefresh</command> the 26.505 + core patch, and <command role="hg-ext-mq">qpush</command> back 26.506 + to the UI patch to continue where you left off.</para> 26.507 + </sect2> 26.508 + </sect1> 26.509 + 26.510 + <sect1 id="sec:mq:adv-patch"> 26.511 + <title>More about patches</title> 26.512 + 26.513 + <para id="x_3e5">MQ uses the GNU <command>patch</command> command to apply 26.514 + patches, so it's helpful to know a few more detailed aspects of 26.515 + how <command>patch</command> works, and about patches 26.516 + themselves.</para> 26.517 + 26.518 + <sect2> 26.519 + <title>The strip count</title> 26.520 + 26.521 + <para id="x_3e6">If you look at the file headers in a patch, you will 26.522 + notice that the pathnames usually have an extra component on 26.523 + the front that isn't present in the actual path name. This is 26.524 + a holdover from the way that people used to generate patches 26.525 + (people still do this, but it's somewhat rare with modern 26.526 + revision control tools).</para> 26.527 + 26.528 + <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide 26.529 + that she wanted to create a patch. So she'd rename her 26.530 + working directory, unpack the tarball again (hence the need 26.531 + for the rename), and use the <option 26.532 + role="cmd-opt-diff">-r</option> and <option 26.533 + role="cmd-opt-diff">-N</option> options to 26.534 + <command>diff</command> to recursively generate a patch 26.535 + between the unmodified directory and the modified one. The 26.536 + result would be that the name of the unmodified directory 26.537 + would be at the front of the left-hand path in every file 26.538 + header, and the name of the modified directory would be at the 26.539 + front of the right-hand path.</para> 26.540 + 26.541 + <para id="x_3e8">Since someone receiving a patch from the Alices of the net 26.542 + would be unlikely to have unmodified and modified directories 26.543 + with exactly the same names, the <command>patch</command> 26.544 + command has a <option role="cmd-opt-patch">-p</option> option 26.545 + that indicates the number of leading path name components to 26.546 + strip when trying to apply a patch. This number is called the 26.547 + <emphasis>strip count</emphasis>.</para> 26.548 + 26.549 + <para id="x_3e9">An option of <quote><literal>-p1</literal></quote> means 26.550 + <quote>use a strip count of one</quote>. If 26.551 + <command>patch</command> sees a file name 26.552 + <filename>foo/bar/baz</filename> in a file header, it will 26.553 + strip <filename>foo</filename> and try to patch a file named 26.554 + <filename>bar/baz</filename>. (Strictly speaking, the strip 26.555 + count refers to the number of <emphasis>path 26.556 + separators</emphasis> (and the components that go with them 26.557 + ) to strip. A strip count of one will turn 26.558 + <filename>foo/bar</filename> into <filename>bar</filename>, 26.559 + but <filename>/foo/bar</filename> (notice the extra leading 26.560 + slash) into <filename>foo/bar</filename>.)</para> 26.561 + 26.562 + <para id="x_3ea">The <quote>standard</quote> strip count for patches is 26.563 + one; almost all patches contain one leading path name 26.564 + component that needs to be stripped. Mercurial's <command 26.565 + role="hg-cmd">hg diff</command> command generates path names 26.566 + in this form, and the <command role="hg-cmd">hg 26.567 + import</command> command and MQ expect patches to have a 26.568 + strip count of one.</para> 26.569 + 26.570 + <para id="x_3eb">If you receive a patch from someone that you want to add 26.571 + to your patch queue, and the patch needs a strip count other 26.572 + than one, you cannot just <command 26.573 + role="hg-ext-mq">qimport</command> the patch, because 26.574 + <command role="hg-ext-mq">qimport</command> does not yet have 26.575 + a <literal>-p</literal> option (see <ulink role="hg-bug" 26.576 + url="http://www.selenic.com/mercurial/bts/issue311">issue 26.577 + 311</ulink>). Your best bet is to <command 26.578 + role="hg-ext-mq">qnew</command> a patch of your own, then 26.579 + use <command>patch -pN</command> to apply their patch, 26.580 + followed by <command role="hg-cmd">hg addremove</command> to 26.581 + pick up any files added or removed by the patch, followed by 26.582 + <command role="hg-ext-mq">hg qrefresh</command>. This 26.583 + complexity may become unnecessary; see <ulink role="hg-bug" 26.584 + url="http://www.selenic.com/mercurial/bts/issue311">issue 26.585 + 311</ulink> for details. 26.586 + </para> 26.587 + </sect2> 26.588 + 26.589 + <sect2> 26.590 + <title>Strategies for applying a patch</title> 26.591 + 26.592 + <para id="x_3ec">When <command>patch</command> applies a hunk, it tries a 26.593 + handful of successively less accurate strategies to try to 26.594 + make the hunk apply. This falling-back technique often makes 26.595 + it possible to take a patch that was generated against an old 26.596 + version of a file, and apply it against a newer version of 26.597 + that file.</para> 26.598 + 26.599 + <para id="x_3ed">First, <command>patch</command> tries an exact match, 26.600 + where the line numbers, the context, and the text to be 26.601 + modified must apply exactly. If it cannot make an exact 26.602 + match, it tries to find an exact match for the context, 26.603 + without honouring the line numbering information. If this 26.604 + succeeds, it prints a line of output saying that the hunk was 26.605 + applied, but at some <emphasis>offset</emphasis> from the 26.606 + original line number.</para> 26.607 + 26.608 + <para id="x_3ee">If a context-only match fails, <command>patch</command> 26.609 + removes the first and last lines of the context, and tries a 26.610 + <emphasis>reduced</emphasis> context-only match. If the hunk 26.611 + with reduced context succeeds, it prints a message saying that 26.612 + it applied the hunk with a <emphasis>fuzz factor</emphasis> 26.613 + (the number after the fuzz factor indicates how many lines of 26.614 + context <command>patch</command> had to trim before the patch 26.615 + applied).</para> 26.616 + 26.617 + <para id="x_3ef">When neither of these techniques works, 26.618 + <command>patch</command> prints a message saying that the hunk 26.619 + in question was rejected. It saves rejected hunks (also 26.620 + simply called <quote>rejects</quote>) to a file with the same 26.621 + name, and an added <filename role="special">.rej</filename> 26.622 + extension. It also saves an unmodified copy of the file with 26.623 + a <filename role="special">.orig</filename> extension; the 26.624 + copy of the file without any extensions will contain any 26.625 + changes made by hunks that <emphasis>did</emphasis> apply 26.626 + cleanly. If you have a patch that modifies 26.627 + <filename>foo</filename> with six hunks, and one of them fails 26.628 + to apply, you will have: an unmodified 26.629 + <filename>foo.orig</filename>, a <filename>foo.rej</filename> 26.630 + containing one hunk, and <filename>foo</filename>, containing 26.631 + the changes made by the five successful hunks.</para> 26.632 + </sect2> 26.633 + 26.634 + <sect2> 26.635 + <title>Some quirks of patch representation</title> 26.636 + 26.637 + <para id="x_3f0">There are a few useful things to know about how 26.638 + <command>patch</command> works with files.</para> 26.639 + <itemizedlist> 26.640 + <listitem><para id="x_3f1">This should already be obvious, but 26.641 + <command>patch</command> cannot handle binary 26.642 + files.</para> 26.643 + </listitem> 26.644 + <listitem><para id="x_3f2">Neither does it care about the executable bit; 26.645 + it creates new files as readable, but not 26.646 + executable.</para> 26.647 + </listitem> 26.648 + <listitem><para id="x_3f3"><command>patch</command> treats the removal of 26.649 + a file as a diff between the file to be removed and the 26.650 + empty file. So your idea of <quote>I deleted this 26.651 + file</quote> looks like <quote>every line of this file 26.652 + was deleted</quote> in a patch.</para> 26.653 + </listitem> 26.654 + <listitem><para id="x_3f4">It treats the addition of a file as a diff 26.655 + between the empty file and the file to be added. So in a 26.656 + patch, your idea of <quote>I added this file</quote> looks 26.657 + like <quote>every line of this file was 26.658 + added</quote>.</para> 26.659 + </listitem> 26.660 + <listitem><para id="x_3f5">It treats a renamed file as the removal of the 26.661 + old name, and the addition of the new name. This means 26.662 + that renamed files have a big footprint in patches. (Note 26.663 + also that Mercurial does not currently try to infer when 26.664 + files have been renamed or copied in a patch.)</para> 26.665 + </listitem> 26.666 + <listitem><para id="x_3f6"><command>patch</command> cannot represent 26.667 + empty files, so you cannot use a patch to represent the 26.668 + notion <quote>I added this empty file to the 26.669 + tree</quote>.</para> 26.670 + </listitem></itemizedlist> 26.671 + </sect2> 26.672 + 26.673 + <sect2> 26.674 + <title>Beware the fuzz</title> 26.675 + 26.676 + <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor, 26.677 + will often be completely successful, these inexact techniques 26.678 + naturally leave open the possibility of corrupting the patched 26.679 + file. The most common cases typically involve applying a 26.680 + patch twice, or at an incorrect location in the file. If 26.681 + <command>patch</command> or <command 26.682 + role="hg-ext-mq">qpush</command> ever mentions an offset or 26.683 + fuzz factor, you should make sure that the modified files are 26.684 + correct afterwards.</para> 26.685 + 26.686 + <para id="x_3f8">It's often a good idea to refresh a patch that has applied 26.687 + with an offset or fuzz factor; refreshing the patch generates 26.688 + new context information that will make it apply cleanly. I 26.689 + say <quote>often,</quote> not <quote>always,</quote> because 26.690 + sometimes refreshing a patch will make it fail to apply 26.691 + against a different revision of the underlying files. In some 26.692 + cases, such as when you're maintaining a patch that must sit 26.693 + on top of multiple versions of a source tree, it's acceptable 26.694 + to have a patch apply with some fuzz, provided you've verified 26.695 + the results of the patching process in such cases.</para> 26.696 + </sect2> 26.697 + 26.698 + <sect2> 26.699 + <title>Handling rejection</title> 26.700 + 26.701 + <para id="x_3f9">If <command role="hg-ext-mq">qpush</command> fails to 26.702 + apply a patch, it will print an error message and exit. If it 26.703 + has left <filename role="special">.rej</filename> files 26.704 + behind, it is usually best to fix up the rejected hunks before 26.705 + you push more patches or do any further work.</para> 26.706 + 26.707 + <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly, 26.708 + and no longer does because you've changed the underlying code 26.709 + that your patches are based on, Mercurial Queues can help; see 26.710 + <xref linkend="sec:mq:merge"/> for details.</para> 26.711 + 26.712 + <para id="x_3fb">Unfortunately, there aren't any great techniques for 26.713 + dealing with rejected hunks. Most often, you'll need to view 26.714 + the <filename role="special">.rej</filename> file and edit the 26.715 + target file, applying the rejected hunks by hand.</para> 26.716 + 26.717 + <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author 26.718 + of Mercurial Queues), wrote a tool called 26.719 + <command>mpatch</command> (<ulink 26.720 + url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 26.721 + which takes a simple approach to automating the application of 26.722 + hunks rejected by <command>patch</command>. The 26.723 + <command>mpatch</command> command can help with four common 26.724 + reasons that a hunk may be rejected:</para> 26.725 + 26.726 + <itemizedlist> 26.727 + <listitem><para id="x_3fe">The context in the middle of a hunk has 26.728 + changed.</para> 26.729 + </listitem> 26.730 + <listitem><para id="x_3ff">A hunk is missing some context at the 26.731 + beginning or end.</para> 26.732 + </listitem> 26.733 + <listitem><para id="x_400">A large hunk might apply better&emdash;either 26.734 + entirely or in part&emdash;if it was broken up into 26.735 + smaller hunks.</para> 26.736 + </listitem> 26.737 + <listitem><para id="x_401">A hunk removes lines with slightly different 26.738 + content than those currently present in the file.</para> 26.739 + </listitem></itemizedlist> 26.740 + 26.741 + <para id="x_402">If you use <command>mpatch</command>, you 26.742 + should be doubly careful to check your results when you're 26.743 + done. In fact, <command>mpatch</command> enforces this method 26.744 + of double-checking the tool's output, by automatically 26.745 + dropping you into a merge program when it has done its job, so 26.746 + that you can verify its work and finish off any remaining 26.747 + merges.</para> 26.748 + </sect2> 26.749 + </sect1> 26.750 + 26.751 + <sect1> 26.752 + <title>More on patch management</title> 26.753 + 26.754 + <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting 26.755 + to perform other kinds of patch management operations.</para> 26.756 + 26.757 + <sect2> 26.758 + <title>Deleting unwanted patches</title> 26.759 + 26.760 + <para id="x_6dc">If you want to get rid of a patch, use the <command 26.761 + role="hg-ext-mq">hg qdelete</command> command to delete the 26.762 + patch file and remove its entry from the patch series. If you 26.763 + try to delete a patch that is still applied, <command 26.764 + role="hg-ext-mq">hg qdelete</command> will refuse.</para> 26.765 + 26.766 + &interaction.ch11-qdelete.go; 26.767 + </sect2> 26.768 + 26.769 + <sect2> 26.770 + <title>Converting to and from permanent revisions</title> 26.771 + 26.772 + <para id="x_6dd">Once you're done working on a patch and want to 26.773 + turn it into a permanent changeset, use the <command 26.774 + role="hg-ext-mq">hg qfinish</command> command. Pass a revision 26.775 + to the command to identify the patch that you want to turn into 26.776 + a regular changeset; this patch must already be applied.</para> 26.777 + 26.778 + &interaction.ch11-qdelete.convert; 26.779 + 26.780 + <para id="x_6e0">The <command role="hg-ext-mq">hg qfinish</command> command 26.781 + accepts an <option>--all</option> or <option>-a</option> 26.782 + option, which turns all applied patches into regular 26.783 + changesets.</para> 26.784 + 26.785 + <para id="x_6de">It is also possible to turn an existing changeset into a 26.786 + patch, by passing the <option>-r</option> option to <command 26.787 + role="hg-ext-mq">hg qimport</command>.</para> 26.788 + 26.789 + &interaction.ch11-qdelete.import; 26.790 + 26.791 + <para id="x_6df">Note that it only makes sense to convert a changeset into 26.792 + a patch if you have not propagated that changeset into any 26.793 + other repositories. The imported changeset's ID will change 26.794 + every time you refresh the patch, which will make Mercurial 26.795 + treat it as unrelated to the original changeset if you have 26.796 + pushed it somewhere else.</para> 26.797 + </sect2> 26.798 + </sect1> 26.799 + 26.800 + <sect1 id="sec:mq:perf"> 26.801 + <title>Getting the best performance out of MQ</title> 26.802 + 26.803 + <para id="x_403">MQ is very efficient at handling a large number 26.804 + of patches. I ran some performance experiments in mid-2006 for a 26.805 + talk that I gave at the 2006 EuroPython conference (on modern 26.806 + hardware, you should expect better performance than you'll see 26.807 + below). I used as my data set the Linux 2.6.17-mm1 patch 26.808 + series, which consists of 1,738 patches. I applied these on top 26.809 + of a Linux kernel repository containing all 27,472 revisions 26.810 + between Linux 2.6.12-rc2 and Linux 2.6.17.</para> 26.811 + 26.812 + <para id="x_404">On my old, slow laptop, I was able to <command 26.813 + role="hg-cmd">hg qpush <option 26.814 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> all 26.815 + 1,738 patches in 3.5 minutes, and <command role="hg-cmd">hg qpop 26.816 + <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> 26.817 + them all in 30 seconds. (On a newer laptop, the time to push 26.818 + all patches dropped to two minutes.) I could <command 26.819 + role="hg-ext-mq">qrefresh</command> one of the biggest patches 26.820 + (which made 22,779 lines of changes to 287 files) in 6.6 26.821 + seconds.</para> 26.822 + 26.823 + <para id="x_405">Clearly, MQ is well suited to working in large trees, but 26.824 + there are a few tricks you can use to get the best performance 26.825 + of it.</para> 26.826 + 26.827 + <para id="x_406">First of all, try to <quote>batch</quote> operations 26.828 + together. Every time you run <command 26.829 + role="hg-ext-mq">qpush</command> or <command 26.830 + role="hg-ext-mq">qpop</command>, these commands scan the 26.831 + working directory once to make sure you haven't made some 26.832 + changes and then forgotten to run <command 26.833 + role="hg-ext-mq">qrefresh</command>. On a small tree, the 26.834 + time that this scan takes is unnoticeable. However, on a 26.835 + medium-sized tree (containing tens of thousands of files), it 26.836 + can take a second or more.</para> 26.837 + 26.838 + <para id="x_407">The <command role="hg-ext-mq">qpush</command> and <command 26.839 + role="hg-ext-mq">qpop</command> commands allow you to push and 26.840 + pop multiple patches at a time. You can identify the 26.841 + <quote>destination patch</quote> that you want to end up at. 26.842 + When you <command role="hg-ext-mq">qpush</command> with a 26.843 + destination specified, it will push patches until that patch is 26.844 + at the top of the applied stack. When you <command 26.845 + role="hg-ext-mq">qpop</command> to a destination, MQ will pop 26.846 + patches until the destination patch is at the top.</para> 26.847 + 26.848 + <para id="x_408">You can identify a destination patch using either the name 26.849 + of the patch, or by number. If you use numeric addressing, 26.850 + patches are counted from zero; this means that the first patch 26.851 + is zero, the second is one, and so on.</para> 26.852 + </sect1> 26.853 + 26.854 + <sect1 id="sec:mq:merge"> 26.855 + <title>Updating your patches when the underlying code 26.856 + changes</title> 26.857 + 26.858 + <para id="x_409">It's common to have a stack of patches on top of an 26.859 + underlying repository that you don't modify directly. If you're 26.860 + working on changes to third-party code, or on a feature that is 26.861 + taking longer to develop than the rate of change of the code 26.862 + beneath, you will often need to sync up with the underlying 26.863 + code, and fix up any hunks in your patches that no longer apply. 26.864 + This is called <emphasis>rebasing</emphasis> your patch 26.865 + series.</para> 26.866 + 26.867 + <para id="x_40a">The simplest way to do this is to <command role="hg-cmd">hg 26.868 + qpop <option role="hg-ext-mq-cmd-qpop-opt">hg 26.869 + -a</option></command> your patches, then <command 26.870 + role="hg-cmd">hg pull</command> changes into the underlying 26.871 + repository, and finally <command role="hg-cmd">hg qpush <option 26.872 + role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your 26.873 + patches again. MQ will stop pushing any time it runs across a 26.874 + patch that fails to apply during conflicts, allowing you to fix 26.875 + your conflicts, <command role="hg-ext-mq">qrefresh</command> the 26.876 + affected patch, and continue pushing until you have fixed your 26.877 + entire stack.</para> 26.878 + 26.879 + <para id="x_40b">This approach is easy to use and works well if you don't 26.880 + expect changes to the underlying code to affect how well your 26.881 + patches apply. If your patch stack touches code that is modified 26.882 + frequently or invasively in the underlying repository, however, 26.883 + fixing up rejected hunks by hand quickly becomes 26.884 + tiresome.</para> 26.885 + 26.886 + <para id="x_40c">It's possible to partially automate the rebasing process. 26.887 + If your patches apply cleanly against some revision of the 26.888 + underlying repo, MQ can use this information to help you to 26.889 + resolve conflicts between your patches and a different 26.890 + revision.</para> 26.891 + 26.892 + <para id="x_40d">The process is a little involved.</para> 26.893 + <orderedlist> 26.894 + <listitem><para id="x_40e">To begin, <command role="hg-cmd">hg qpush 26.895 + -a</command> all of your patches on top of the revision 26.896 + where you know that they apply cleanly.</para> 26.897 + </listitem> 26.898 + <listitem><para id="x_40f">Save a backup copy of your patch directory using 26.899 + <command role="hg-cmd">hg qsave <option 26.900 + role="hg-ext-mq-cmd-qsave-opt">hg -e</option> <option 26.901 + role="hg-ext-mq-cmd-qsave-opt">hg -c</option></command>. 26.902 + This prints the name of the directory that it has saved the 26.903 + patches in. It will save the patches to a directory called 26.904 + <filename role="special" 26.905 + class="directory">.hg/patches.N</filename>, where 26.906 + <literal>N</literal> is a small integer. It also commits a 26.907 + <quote>save changeset</quote> on top of your applied 26.908 + patches; this is for internal book-keeping, and records the 26.909 + states of the <filename role="special">series</filename> and 26.910 + <filename role="special">status</filename> files.</para> 26.911 + </listitem> 26.912 + <listitem><para id="x_410">Use <command role="hg-cmd">hg pull</command> to 26.913 + bring new changes into the underlying repository. (Don't 26.914 + run <command role="hg-cmd">hg pull -u</command>; see below 26.915 + for why.)</para> 26.916 + </listitem> 26.917 + <listitem><para id="x_411">Update to the new tip revision, using <command 26.918 + role="hg-cmd">hg update <option 26.919 + role="hg-opt-update">-C</option></command> to override 26.920 + the patches you have pushed.</para> 26.921 + </listitem> 26.922 + <listitem><para id="x_412">Merge all patches using <command>hg qpush -m 26.923 + -a</command>. The <option 26.924 + role="hg-ext-mq-cmd-qpush-opt">-m</option> option to 26.925 + <command role="hg-ext-mq">qpush</command> tells MQ to 26.926 + perform a three-way merge if the patch fails to 26.927 + apply.</para> 26.928 + </listitem></orderedlist> 26.929 + 26.930 + <para id="x_413">During the <command role="hg-cmd">hg qpush <option 26.931 + role="hg-ext-mq-cmd-qpush-opt">hg -m</option></command>, 26.932 + each patch in the <filename role="special">series</filename> 26.933 + file is applied normally. If a patch applies with fuzz or 26.934 + rejects, MQ looks at the queue you <command 26.935 + role="hg-ext-mq">qsave</command>d, and performs a three-way 26.936 + merge with the corresponding changeset. This merge uses 26.937 + Mercurial's normal merge machinery, so it may pop up a GUI merge 26.938 + tool to help you to resolve problems.</para> 26.939 + 26.940 + <para id="x_414">When you finish resolving the effects of a patch, MQ 26.941 + refreshes your patch based on the result of the merge.</para> 26.942 + 26.943 + <para id="x_415">At the end of this process, your repository will have one 26.944 + extra head from the old patch queue, and a copy of the old patch 26.945 + queue will be in <filename role="special" 26.946 + class="directory">.hg/patches.N</filename>. You can remove the 26.947 + extra head using <command role="hg-cmd">hg qpop -a -n 26.948 + patches.N</command> or <command role="hg-cmd">hg 26.949 + strip</command>. You can delete <filename role="special" 26.950 + class="directory">.hg/patches.N</filename> once you are sure 26.951 + that you no longer need it as a backup.</para> 26.952 + </sect1> 26.953 + 26.954 + <sect1> 26.955 + <title>Identifying patches</title> 26.956 + 26.957 + <para id="x_416">MQ commands that work with patches let you refer to a patch 26.958 + either by using its name or by a number. By name is obvious 26.959 + enough; pass the name <filename>foo.patch</filename> to <command 26.960 + role="hg-ext-mq">qpush</command>, for example, and it will 26.961 + push patches until <filename>foo.patch</filename> is 26.962 + applied.</para> 26.963 + 26.964 + <para id="x_417">As a shortcut, you can refer to a patch using both a name 26.965 + and a numeric offset; <literal>foo.patch-2</literal> means 26.966 + <quote>two patches before <literal>foo.patch</literal></quote>, 26.967 + while <literal>bar.patch+4</literal> means <quote>four patches 26.968 + after <literal>bar.patch</literal></quote>.</para> 26.969 + 26.970 + <para id="x_418">Referring to a patch by index isn't much different. The 26.971 + first patch printed in the output of <command 26.972 + role="hg-ext-mq">qseries</command> is patch zero (yes, it's 26.973 + one of those start-at-zero counting systems); the second is 26.974 + patch one; and so on.</para> 26.975 + 26.976 + <para id="x_419">MQ also makes it easy to work with patches when you are 26.977 + using normal Mercurial commands. Every command that accepts a 26.978 + changeset ID will also accept the name of an applied patch. MQ 26.979 + augments the tags normally in the repository with an eponymous 26.980 + one for each applied patch. In addition, the special tags 26.981 + <literal role="tag">qbase</literal> and 26.982 + <literal role="tag">qtip</literal> identify 26.983 + the <quote>bottom-most</quote> and topmost applied patches, 26.984 + respectively.</para> 26.985 + 26.986 + <para id="x_41a">These additions to Mercurial's normal tagging capabilities 26.987 + make dealing with patches even more of a breeze.</para> 26.988 + <itemizedlist> 26.989 + <listitem><para id="x_41b">Want to patchbomb a mailing list with your 26.990 + latest series of changes?</para> 26.991 + <programlisting>hg email qbase:qtip</programlisting> 26.992 + <para id="x_41c"> (Don't know what <quote>patchbombing</quote> is? See 26.993 + <xref linkend="sec:hgext:patchbomb"/>.)</para> 26.994 + </listitem> 26.995 + <listitem><para id="x_41d">Need to see all of the patches since 26.996 + <literal>foo.patch</literal> that have touched files in a 26.997 + subdirectory of your tree?</para> 26.998 + <programlisting>hg log -r foo.patch:qtip subdir</programlisting> 26.999 + </listitem> 26.1000 + </itemizedlist> 26.1001 + 26.1002 + <para id="x_41e">Because MQ makes the names of patches available to the rest 26.1003 + of Mercurial through its normal internal tag machinery, you 26.1004 + don't need to type in the entire name of a patch when you want 26.1005 + to identify it by name.</para> 26.1006 + 26.1007 + <para id="x_41f">Another nice consequence of representing patch names as tags 26.1008 + is that when you run the <command role="hg-cmd">hg log</command> 26.1009 + command, it will display a patch's name as a tag, simply as part 26.1010 + of its normal output. This makes it easy to visually 26.1011 + distinguish applied patches from underlying 26.1012 + <quote>normal</quote> revisions. The following example shows a 26.1013 + few normal Mercurial commands in use with applied 26.1014 + patches.</para> 26.1015 + 26.1016 + &interaction.mq.id.output; 26.1017 + </sect1> 26.1018 + 26.1019 + <sect1> 26.1020 + <title>Useful things to know about</title> 26.1021 + 26.1022 + <para id="x_420">There are a number of aspects of MQ usage that don't fit 26.1023 + tidily into sections of their own, but that are good to know. 26.1024 + Here they are, in one place.</para> 26.1025 + 26.1026 + <itemizedlist> 26.1027 + <listitem><para id="x_421">Normally, when you <command 26.1028 + role="hg-ext-mq">qpop</command> a patch and <command 26.1029 + role="hg-ext-mq">qpush</command> it again, the changeset 26.1030 + that represents the patch after the pop/push will have a 26.1031 + <emphasis>different identity</emphasis> than the changeset 26.1032 + that represented the hash beforehand. See <xref 26.1033 + linkend="sec:mqref:cmd:qpush"/> for 26.1034 + information as to why this is.</para> 26.1035 + </listitem> 26.1036 + <listitem><para id="x_422">It's not a good idea to <command 26.1037 + role="hg-cmd">hg merge</command> changes from another 26.1038 + branch with a patch changeset, at least if you want to 26.1039 + maintain the <quote>patchiness</quote> of that changeset and 26.1040 + changesets below it on the patch stack. If you try to do 26.1041 + this, it will appear to succeed, but MQ will become 26.1042 + confused.</para> 26.1043 + </listitem></itemizedlist> 26.1044 + </sect1> 26.1045 + 26.1046 + <sect1 id="sec:mq:repo"> 26.1047 + <title>Managing patches in a repository</title> 26.1048 + 26.1049 + <para id="x_423">Because MQ's <filename role="special" 26.1050 + class="directory">.hg/patches</filename> directory resides 26.1051 + outside a Mercurial repository's working directory, the 26.1052 + <quote>underlying</quote> Mercurial repository knows nothing 26.1053 + about the management or presence of patches.</para> 26.1054 + 26.1055 + <para id="x_424">This presents the interesting possibility of managing the 26.1056 + contents of the patch directory as a Mercurial repository in its 26.1057 + own right. This can be a useful way to work. For example, you 26.1058 + can work on a patch for a while, <command 26.1059 + role="hg-ext-mq">qrefresh</command> it, then <command 26.1060 + role="hg-cmd">hg commit</command> the current state of the 26.1061 + patch. This lets you <quote>roll back</quote> to that version 26.1062 + of the patch later on.</para> 26.1063 + 26.1064 + <para id="x_425">You can then share different versions of the same patch 26.1065 + stack among multiple underlying repositories. I use this when I 26.1066 + am developing a Linux kernel feature. I have a pristine copy of 26.1067 + my kernel sources for each of several CPU architectures, and a 26.1068 + cloned repository under each that contains the patches I am 26.1069 + working on. When I want to test a change on a different 26.1070 + architecture, I push my current patches to the patch repository 26.1071 + associated with that kernel tree, pop and push all of my 26.1072 + patches, and build and test that kernel.</para> 26.1073 + 26.1074 + <para id="x_426">Managing patches in a repository makes it possible for 26.1075 + multiple developers to work on the same patch series without 26.1076 + colliding with each other, all on top of an underlying source 26.1077 + base that they may or may not control.</para> 26.1078 + 26.1079 + <sect2> 26.1080 + <title>MQ support for patch repositories</title> 26.1081 + 26.1082 + <para id="x_427">MQ helps you to work with the <filename role="special" 26.1083 + class="directory">.hg/patches</filename> directory as a 26.1084 + repository; when you prepare a repository for working with 26.1085 + patches using <command role="hg-ext-mq">qinit</command>, you 26.1086 + can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg 26.1087 + -c</option> option to create the <filename role="special" 26.1088 + class="directory">.hg/patches</filename> directory as a 26.1089 + Mercurial repository.</para> 26.1090 + 26.1091 + <note> 26.1092 + <para id="x_428"> If you forget to use the <option 26.1093 + role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you 26.1094 + can simply go into the <filename role="special" 26.1095 + class="directory">.hg/patches</filename> directory at any 26.1096 + time and run <command role="hg-cmd">hg init</command>. 26.1097 + Don't forget to add an entry for the <filename 26.1098 + role="special">status</filename> file to the <filename 26.1099 + role="special">.hgignore</filename> file, though</para> 26.1100 + 26.1101 + <para id="x_429"> (<command role="hg-cmd">hg qinit <option 26.1102 + role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command> 26.1103 + does this for you automatically); you 26.1104 + <emphasis>really</emphasis> don't want to manage the 26.1105 + <filename role="special">status</filename> file.</para> 26.1106 + </note> 26.1107 + 26.1108 + <para id="x_42a">As a convenience, if MQ notices that the <filename 26.1109 + class="directory">.hg/patches</filename> directory is a 26.1110 + repository, it will automatically <command role="hg-cmd">hg 26.1111 + add</command> every patch that you create and import.</para> 26.1112 + 26.1113 + <para id="x_42b">MQ provides a shortcut command, <command 26.1114 + role="hg-ext-mq">qcommit</command>, that runs <command 26.1115 + role="hg-cmd">hg commit</command> in the <filename 26.1116 + role="special" class="directory">.hg/patches</filename> 26.1117 + directory. This saves some bothersome typing.</para> 26.1118 + 26.1119 + <para id="x_42c">Finally, as a convenience to manage the patch directory, 26.1120 + you can define the alias <command>mq</command> on Unix 26.1121 + systems. For example, on Linux systems using the 26.1122 + <command>bash</command> shell, you can include the following 26.1123 + snippet in your <filename 26.1124 + role="home">~/.bashrc</filename>.</para> 26.1125 + 26.1126 + <programlisting>alias mq=`hg -R $(hg root)/.hg/patches'</programlisting> 26.1127 + 26.1128 + <para id="x_42d">You can then issue commands of the form <command>mq 26.1129 + pull</command> from the main repository.</para> 26.1130 + </sect2> 26.1131 + 26.1132 + <sect2> 26.1133 + <title>A few things to watch out for</title> 26.1134 + 26.1135 + <para id="x_42e">MQ's support for working with a repository full of patches 26.1136 + is limited in a few small respects.</para> 26.1137 + 26.1138 + <para id="x_42f">MQ cannot automatically detect changes that you make to 26.1139 + the patch directory. If you <command role="hg-cmd">hg 26.1140 + pull</command>, manually edit, or <command role="hg-cmd">hg 26.1141 + update</command> changes to patches or the <filename 26.1142 + role="special">series</filename> file, you will have to 26.1143 + <command role="hg-cmd">hg qpop <option 26.1144 + role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and 26.1145 + then <command role="hg-cmd">hg qpush <option 26.1146 + role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in 26.1147 + the underlying repository to see those changes show up there. 26.1148 + If you forget to do this, you can confuse MQ's idea of which 26.1149 + patches are applied.</para> 26.1150 + 26.1151 + </sect2> 26.1152 + </sect1> 26.1153 + <sect1 id="sec:mq:tools"> 26.1154 + <title>Third party tools for working with patches</title> 26.1155 + 26.1156 + <para id="x_430">Once you've been working with patches for a while, you'll 26.1157 + find yourself hungry for tools that will help you to understand 26.1158 + and manipulate the patches you're dealing with.</para> 26.1159 + 26.1160 + <para id="x_431">The <command>diffstat</command> command 26.1161 + <citation>web:diffstat</citation> generates a histogram of the 26.1162 + modifications made to each file in a patch. It provides a good 26.1163 + way to <quote>get a sense of</quote> a patch&emdash;which files 26.1164 + it affects, and how much change it introduces to each file and 26.1165 + as a whole. (I find that it's a good idea to use 26.1166 + <command>diffstat</command>'s <option 26.1167 + role="cmd-opt-diffstat">-p</option> option as a matter of 26.1168 + course, as otherwise it will try to do clever things with 26.1169 + prefixes of file names that inevitably confuse at least 26.1170 + me.)</para> 26.1171 + 26.1172 +&interaction.mq.tools.tools; 26.1173 + 26.1174 + <para id="x_432">The <literal role="package">patchutils</literal> package 26.1175 + <citation>web:patchutils</citation> is invaluable. It provides a 26.1176 + set of small utilities that follow the <quote>Unix 26.1177 + philosophy;</quote> each does one useful thing with a patch. 26.1178 + The <literal role="package">patchutils</literal> command I use 26.1179 + most is <command>filterdiff</command>, which extracts subsets 26.1180 + from a patch file. For example, given a patch that modifies 26.1181 + hundreds of files across dozens of directories, a single 26.1182 + invocation of <command>filterdiff</command> can generate a 26.1183 + smaller patch that only touches files whose names match a 26.1184 + particular glob pattern. See <xref 26.1185 + linkend="mq-collab:tips:interdiff"/> for another 26.1186 + example.</para> 26.1187 + 26.1188 + </sect1> 26.1189 + <sect1> 26.1190 + <title>Good ways to work with patches</title> 26.1191 + 26.1192 + <para id="x_433">Whether you are working on a patch series to submit to a 26.1193 + free software or open source project, or a series that you 26.1194 + intend to treat as a sequence of regular changesets when you're 26.1195 + done, you can use some simple techniques to keep your work well 26.1196 + organized.</para> 26.1197 + 26.1198 + <para id="x_434">Give your patches descriptive names. A good name for a 26.1199 + patch might be <filename>rework-device-alloc.patch</filename>, 26.1200 + because it will immediately give you a hint what the purpose of 26.1201 + the patch is. Long names shouldn't be a problem; you won't be 26.1202 + typing the names often, but you <emphasis>will</emphasis> be 26.1203 + running commands like <command 26.1204 + role="hg-ext-mq">qapplied</command> and <command 26.1205 + role="hg-ext-mq">qtop</command> over and over. Good naming 26.1206 + becomes especially important when you have a number of patches 26.1207 + to work with, or if you are juggling a number of different tasks 26.1208 + and your patches only get a fraction of your attention.</para> 26.1209 + 26.1210 + <para id="x_435">Be aware of what patch you're working on. Use the <command 26.1211 + role="hg-ext-mq">qtop</command> command and skim over the text 26.1212 + of your patches frequently&emdash;for example, using <command 26.1213 + role="hg-cmd">hg tip <option 26.1214 + role="hg-opt-tip">-p</option></command>)&emdash;to be sure 26.1215 + of where you stand. I have several times worked on and <command 26.1216 + role="hg-ext-mq">qrefresh</command>ed a patch other than the 26.1217 + one I intended, and it's often tricky to migrate changes into 26.1218 + the right patch after making them in the wrong one.</para> 26.1219 + 26.1220 + <para id="x_436">For this reason, it is very much worth investing a little 26.1221 + time to learn how to use some of the third-party tools I 26.1222 + described in <xref linkend="sec:mq:tools"/>, 26.1223 + particularly 26.1224 + <command>diffstat</command> and <command>filterdiff</command>. 26.1225 + The former will give you a quick idea of what changes your patch 26.1226 + is making, while the latter makes it easy to splice hunks 26.1227 + selectively out of one patch and into another.</para> 26.1228 + 26.1229 + </sect1> 26.1230 + <sect1> 26.1231 + <title>MQ cookbook</title> 26.1232 + 26.1233 + <sect2> 26.1234 + <title>Manage <quote>trivial</quote> patches</title> 26.1235 + 26.1236 + <para id="x_437">Because the overhead of dropping files into a new 26.1237 + Mercurial repository is so low, it makes a lot of sense to 26.1238 + manage patches this way even if you simply want to make a few 26.1239 + changes to a source tarball that you downloaded.</para> 26.1240 + 26.1241 + <para id="x_438">Begin by downloading and unpacking the source tarball, and 26.1242 + turning it into a Mercurial repository.</para> 26.1243 + 26.1244 + &interaction.mq.tarball.download; 26.1245 + 26.1246 + <para id="x_439">Continue by creating a patch stack and making your 26.1247 + changes.</para> 26.1248 + 26.1249 + &interaction.mq.tarball.qinit; 26.1250 + 26.1251 + <para id="x_43a">Let's say a few weeks or months pass, and your package 26.1252 + author releases a new version. First, bring their changes 26.1253 + into the repository.</para> 26.1254 + 26.1255 + &interaction.mq.tarball.newsource; 26.1256 + 26.1257 + <para id="x_43b">The pipeline starting with <command role="hg-cmd">hg 26.1258 + locate</command> above deletes all files in the working 26.1259 + directory, so that <command role="hg-cmd">hg 26.1260 + commit</command>'s <option 26.1261 + role="hg-opt-commit">--addremove</option> option can 26.1262 + actually tell which files have really been removed in the 26.1263 + newer version of the source.</para> 26.1264 + 26.1265 + <para id="x_43c">Finally, you can apply your patches on top of the new 26.1266 + tree.</para> 26.1267 + 26.1268 + &interaction.mq.tarball.repush; 26.1269 + </sect2> 26.1270 + 26.1271 + <sect2 id="sec:mq:combine"> 26.1272 + <title>Combining entire patches</title> 26.1273 + 26.1274 + <para id="x_43d">MQ provides a command, <command 26.1275 + role="hg-ext-mq">qfold</command> that lets you combine 26.1276 + entire patches. This <quote>folds</quote> the patches you 26.1277 + name, in the order you name them, into the topmost applied 26.1278 + patch, and concatenates their descriptions onto the end of its 26.1279 + description. The patches that you fold must be unapplied 26.1280 + before you fold them.</para> 26.1281 + 26.1282 + <para id="x_43e">The order in which you fold patches matters. If your 26.1283 + topmost applied patch is <literal>foo</literal>, and you 26.1284 + <command role="hg-ext-mq">qfold</command> 26.1285 + <literal>bar</literal> and <literal>quux</literal> into it, 26.1286 + you will end up with a patch that has the same effect as if 26.1287 + you applied first <literal>foo</literal>, then 26.1288 + <literal>bar</literal>, followed by 26.1289 + <literal>quux</literal>.</para> 26.1290 + </sect2> 26.1291 + 26.1292 + <sect2> 26.1293 + <title>Merging part of one patch into another</title> 26.1294 + 26.1295 + <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into 26.1296 + another is more difficult than combining entire 26.1297 + patches.</para> 26.1298 + 26.1299 + <para id="x_440">If you want to move changes to entire files, you can use 26.1300 + <command>filterdiff</command>'s <option 26.1301 + role="cmd-opt-filterdiff">-i</option> and <option 26.1302 + role="cmd-opt-filterdiff">-x</option> options to choose the 26.1303 + modifications to snip out of one patch, concatenating its 26.1304 + output onto the end of the patch you want to merge into. You 26.1305 + usually won't need to modify the patch you've merged the 26.1306 + changes from. Instead, MQ will report some rejected hunks 26.1307 + when you <command role="hg-ext-mq">qpush</command> it (from 26.1308 + the hunks you moved into the other patch), and you can simply 26.1309 + <command role="hg-ext-mq">qrefresh</command> the patch to drop 26.1310 + the duplicate hunks.</para> 26.1311 + 26.1312 + <para id="x_441">If you have a patch that has multiple hunks modifying a 26.1313 + file, and you only want to move a few of those hunks, the job 26.1314 + becomes more messy, but you can still partly automate it. Use 26.1315 + <command>lsdiff -nvv</command> to print some metadata about 26.1316 + the patch.</para> 26.1317 + 26.1318 + &interaction.mq.tools.lsdiff; 26.1319 + 26.1320 + <para id="x_442">This command prints three different kinds of 26.1321 + number:</para> 26.1322 + <itemizedlist> 26.1323 + <listitem><para id="x_443">(in the first column) a <emphasis>file 26.1324 + number</emphasis> to identify each file modified in the 26.1325 + patch;</para> 26.1326 + </listitem> 26.1327 + <listitem><para id="x_444">(on the next line, indented) the line number 26.1328 + within a modified file where a hunk starts; and</para> 26.1329 + </listitem> 26.1330 + <listitem><para id="x_445">(on the same line) a <emphasis>hunk 26.1331 + number</emphasis> to identify that hunk.</para> 26.1332 + </listitem></itemizedlist> 26.1333 + 26.1334 + <para id="x_446">You'll have to use some visual inspection, and reading of 26.1335 + the patch, to identify the file and hunk numbers you'll want, 26.1336 + but you can then pass them to to 26.1337 + <command>filterdiff</command>'s <option 26.1338 + role="cmd-opt-filterdiff">--files</option> and <option 26.1339 + role="cmd-opt-filterdiff">--hunks</option> options, to 26.1340 + select exactly the file and hunk you want to extract.</para> 26.1341 + 26.1342 + <para id="x_447">Once you have this hunk, you can concatenate it onto the 26.1343 + end of your destination patch and continue with the remainder 26.1344 + of <xref linkend="sec:mq:combine"/>.</para> 26.1345 + 26.1346 + </sect2> 26.1347 + </sect1> 26.1348 + <sect1> 26.1349 + <title>Differences between quilt and MQ</title> 26.1350 + 26.1351 + <para id="x_448">If you are already familiar with quilt, MQ provides a 26.1352 + similar command set. There are a few differences in the way 26.1353 + that it works.</para> 26.1354 + 26.1355 + <para id="x_449">You will already have noticed that most quilt commands have 26.1356 + MQ counterparts that simply begin with a 26.1357 + <quote><literal>q</literal></quote>. The exceptions are quilt's 26.1358 + <literal>add</literal> and <literal>remove</literal> commands, 26.1359 + the counterparts for which are the normal Mercurial <command 26.1360 + role="hg-cmd">hg add</command> and <command role="hg-cmd">hg 26.1361 + remove</command> commands. There is no MQ equivalent of the 26.1362 + quilt <literal>edit</literal> command.</para> 26.1363 + 26.1364 + </sect1> 26.1365 +</chapter> 26.1366 + 26.1367 +<!-- 26.1368 +local variables: 26.1369 +sgml-parent-document: ("00book.xml" "book" "chapter") 26.1370 +end: 26.1371 +-->
27.1 --- a/en/ch13-hgext.xml Thu May 07 21:06:49 2009 -0700 27.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 27.3 @@ -1,554 +0,0 @@ 27.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 27.5 - 27.6 -<chapter id="chap:hgext"> 27.7 - <?dbhtml filename="adding-functionality-with-extensions.html"?> 27.8 - <title>Adding functionality with extensions</title> 27.9 - 27.10 - <para id="x_4fe">While the core of Mercurial is quite complete from a 27.11 - functionality standpoint, it's deliberately shorn of fancy 27.12 - features. This approach of preserving simplicity keeps the 27.13 - software easy to deal with for both maintainers and users.</para> 27.14 - 27.15 - <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible 27.16 - command set: you can add features to it as 27.17 - <emphasis>extensions</emphasis> (sometimes known as 27.18 - <emphasis>plugins</emphasis>). We've already discussed a few of 27.19 - these extensions in earlier chapters.</para> 27.20 - <itemizedlist> 27.21 - <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/> 27.22 - covers the <literal role="hg-ext">fetch</literal> extension; 27.23 - this combines pulling new changes and merging them with local 27.24 - changes into a single command, <command 27.25 - role="hg-ext-fetch">fetch</command>.</para> 27.26 - </listitem> 27.27 - <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered 27.28 - several extensions that are useful for hook-related 27.29 - functionality: <literal role="hg-ext">acl</literal> adds 27.30 - access control lists; <literal 27.31 - role="hg-ext">bugzilla</literal> adds integration with the 27.32 - Bugzilla bug tracking system; and <literal 27.33 - role="hg-ext">notify</literal> sends notification emails on 27.34 - new changes.</para> 27.35 - </listitem> 27.36 - <listitem><para id="x_502">The Mercurial Queues patch management extension is 27.37 - so invaluable that it merits two chapters and an appendix all 27.38 - to itself. <xref linkend="chap:mq"/> covers the 27.39 - basics; <xref 27.40 - linkend="chap:mq-collab"/> discusses advanced topics; 27.41 - and <xref linkend="chap:mqref"/> goes into detail on 27.42 - each 27.43 - command.</para> 27.44 - </listitem></itemizedlist> 27.45 - 27.46 - <para id="x_503">In this chapter, we'll cover some of the other extensions that 27.47 - are available for Mercurial, and briefly touch on some of the 27.48 - machinery you'll need to know about if you want to write an 27.49 - extension of your own.</para> 27.50 - <itemizedlist> 27.51 - <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>, 27.52 - we'll discuss the possibility of <emphasis>huge</emphasis> 27.53 - performance improvements using the <literal 27.54 - role="hg-ext">inotify</literal> extension.</para> 27.55 - </listitem></itemizedlist> 27.56 - 27.57 - <sect1 id="sec:hgext:inotify"> 27.58 - <title>Improve performance with the <literal 27.59 - role="hg-ext">inotify</literal> extension</title> 27.60 - 27.61 - <para id="x_505">Are you interested in having some of the most common 27.62 - Mercurial operations run as much as a hundred times faster? 27.63 - Read on!</para> 27.64 - 27.65 - <para id="x_506">Mercurial has great performance under normal circumstances. 27.66 - For example, when you run the <command role="hg-cmd">hg 27.67 - status</command> command, Mercurial has to scan almost every 27.68 - directory and file in your repository so that it can display 27.69 - file status. Many other Mercurial commands need to do the same 27.70 - work behind the scenes; for example, the <command 27.71 - role="hg-cmd">hg diff</command> command uses the status 27.72 - machinery to avoid doing an expensive comparison operation on 27.73 - files that obviously haven't changed.</para> 27.74 - 27.75 - <para id="x_507">Because obtaining file status is crucial to good 27.76 - performance, the authors of Mercurial have optimised this code 27.77 - to within an inch of its life. However, there's no avoiding the 27.78 - fact that when you run <command role="hg-cmd">hg 27.79 - status</command>, Mercurial is going to have to perform at 27.80 - least one expensive system call for each managed file to 27.81 - determine whether it's changed since the last time Mercurial 27.82 - checked. For a sufficiently large repository, this can take a 27.83 - long time.</para> 27.84 - 27.85 - <para id="x_508">To put a number on the magnitude of this effect, I created a 27.86 - repository containing 150,000 managed files. I timed <command 27.87 - role="hg-cmd">hg status</command> as taking ten seconds to 27.88 - run, even when <emphasis>none</emphasis> of those files had been 27.89 - modified.</para> 27.90 - 27.91 - <para id="x_509">Many modern operating systems contain a file notification 27.92 - facility. If a program signs up to an appropriate service, the 27.93 - operating system will notify it every time a file of interest is 27.94 - created, modified, or deleted. On Linux systems, the kernel 27.95 - component that does this is called 27.96 - <literal>inotify</literal>.</para> 27.97 - 27.98 - <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal> 27.99 - extension talks to the kernel's <literal>inotify</literal> 27.100 - component to optimise <command role="hg-cmd">hg status</command> 27.101 - commands. The extension has two components. A daemon sits in 27.102 - the background and receives notifications from the 27.103 - <literal>inotify</literal> subsystem. It also listens for 27.104 - connections from a regular Mercurial command. The extension 27.105 - modifies Mercurial's behavior so that instead of scanning the 27.106 - filesystem, it queries the daemon. Since the daemon has perfect 27.107 - information about the state of the repository, it can respond 27.108 - with a result instantaneously, avoiding the need to scan every 27.109 - directory and file in the repository.</para> 27.110 - 27.111 - <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as 27.112 - taking to run <command role="hg-cmd">hg status</command> on a 27.113 - 150,000 file repository. With the <literal 27.114 - role="hg-ext">inotify</literal> extension enabled, the time 27.115 - dropped to 0.1 seconds, a factor of <emphasis>one 27.116 - hundred</emphasis> faster.</para> 27.117 - 27.118 - <para id="x_50c">Before we continue, please pay attention to some 27.119 - caveats.</para> 27.120 - <itemizedlist> 27.121 - <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal> 27.122 - extension is Linux-specific. Because it interfaces directly 27.123 - to the Linux kernel's <literal>inotify</literal> subsystem, 27.124 - it does not work on other operating systems.</para> 27.125 - </listitem> 27.126 - <listitem><para id="x_50e">It should work on any Linux distribution that 27.127 - was released after early 2005. Older distributions are 27.128 - likely to have a kernel that lacks 27.129 - <literal>inotify</literal>, or a version of 27.130 - <literal>glibc</literal> that does not have the necessary 27.131 - interfacing support.</para> 27.132 - </listitem> 27.133 - <listitem><para id="x_50f">Not all filesystems are suitable for use with 27.134 - the <literal role="hg-ext">inotify</literal> extension. 27.135 - Network filesystems such as NFS are a non-starter, for 27.136 - example, particularly if you're running Mercurial on several 27.137 - systems, all mounting the same network filesystem. The 27.138 - kernel's <literal>inotify</literal> system has no way of 27.139 - knowing about changes made on another system. Most local 27.140 - filesystems (e.g. ext3, XFS, ReiserFS) should work 27.141 - fine.</para> 27.142 - </listitem></itemizedlist> 27.143 - 27.144 - <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is 27.145 - not yet shipped with Mercurial as of May 2007, so it's a little 27.146 - more involved to set up than other extensions. But the 27.147 - performance improvement is worth it!</para> 27.148 - 27.149 - <para id="x_511">The extension currently comes in two parts: a set of patches 27.150 - to the Mercurial source code, and a library of Python bindings 27.151 - to the <literal>inotify</literal> subsystem.</para> 27.152 - <note> 27.153 - <para id="x_512"> There are <emphasis>two</emphasis> Python 27.154 - <literal>inotify</literal> binding libraries. One of them is 27.155 - called <literal>pyinotify</literal>, and is packaged by some 27.156 - Linux distributions as <literal>python-inotify</literal>. 27.157 - This is <emphasis>not</emphasis> the one you'll need, as it is 27.158 - too buggy and inefficient to be practical.</para> 27.159 - </note> 27.160 - <para id="x_513">To get going, it's best to already have a functioning copy 27.161 - of Mercurial installed.</para> 27.162 - <note> 27.163 - <para id="x_514"> If you follow the instructions below, you'll be 27.164 - <emphasis>replacing</emphasis> and overwriting any existing 27.165 - installation of Mercurial that you might already have, using 27.166 - the latest <quote>bleeding edge</quote> Mercurial code. Don't 27.167 - say you weren't warned!</para> 27.168 - </note> 27.169 - <orderedlist> 27.170 - <listitem><para id="x_515">Clone the Python <literal>inotify</literal> 27.171 - binding repository. Build and install it.</para> 27.172 - <programlisting>hg clone http://hg.kublai.com/python/inotify 27.173 -cd inotify 27.174 -python setup.py build --force 27.175 -sudo python setup.py install --skip-build</programlisting> 27.176 - </listitem> 27.177 - <listitem><para id="x_516">Clone the <filename 27.178 - class="directory">crew</filename> Mercurial repository. 27.179 - Clone the <literal role="hg-ext">inotify</literal> patch 27.180 - repository so that Mercurial Queues will be able to apply 27.181 - patches to your cope of the <filename 27.182 - class="directory">crew</filename> repository.</para> 27.183 - <programlisting>hg clone http://hg.intevation.org/mercurial/crew 27.184 -hg clone crew inotify 27.185 -hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting> 27.186 - </listitem> 27.187 - <listitem><para id="x_517">Make sure that you have the Mercurial Queues 27.188 - extension, <literal role="hg-ext">mq</literal>, enabled. If 27.189 - you've never used MQ, read <xref 27.190 - linkend="sec:mq:start"/> to get started 27.191 - quickly.</para> 27.192 - </listitem> 27.193 - <listitem><para id="x_518">Go into the <filename 27.194 - class="directory">inotify</filename> repo, and apply all 27.195 - of the <literal role="hg-ext">inotify</literal> patches 27.196 - using the <option role="hg-ext-mq-cmd-qpush-opt">hg 27.197 - -a</option> option to the <command 27.198 - role="hg-ext-mq">qpush</command> command.</para> 27.199 - <programlisting>cd inotify 27.200 -hg qpush -a</programlisting> 27.201 - </listitem> 27.202 - <listitem><para id="x_519"> If you get an error message from <command 27.203 - role="hg-ext-mq">qpush</command>, you should not continue. 27.204 - Instead, ask for help.</para> 27.205 - </listitem> 27.206 - <listitem><para id="x_51a">Build and install the patched version of 27.207 - Mercurial.</para> 27.208 - <programlisting>python setup.py build --force 27.209 -sudo python setup.py install --skip-build</programlisting> 27.210 - </listitem> 27.211 - </orderedlist> 27.212 - <para id="x_51b">Once you've build a suitably patched version of Mercurial, 27.213 - all you need to do to enable the <literal 27.214 - role="hg-ext">inotify</literal> extension is add an entry to 27.215 - your <filename role="special">~/.hgrc</filename>.</para> 27.216 - <programlisting>[extensions] inotify =</programlisting> 27.217 - <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension 27.218 - is enabled, Mercurial will automatically and transparently start 27.219 - the status daemon the first time you run a command that needs 27.220 - status in a repository. It runs one status daemon per 27.221 - repository.</para> 27.222 - 27.223 - <para id="x_51d">The status daemon is started silently, and runs in the 27.224 - background. If you look at a list of running processes after 27.225 - you've enabled the <literal role="hg-ext">inotify</literal> 27.226 - extension and run a few commands in different repositories, 27.227 - you'll thus see a few <literal>hg</literal> processes sitting 27.228 - around, waiting for updates from the kernel and queries from 27.229 - Mercurial.</para> 27.230 - 27.231 - <para id="x_51e">The first time you run a Mercurial command in a repository 27.232 - when you have the <literal role="hg-ext">inotify</literal> 27.233 - extension enabled, it will run with about the same performance 27.234 - as a normal Mercurial command. This is because the status 27.235 - daemon needs to perform a normal status scan so that it has a 27.236 - baseline against which to apply later updates from the kernel. 27.237 - However, <emphasis>every</emphasis> subsequent command that does 27.238 - any kind of status check should be noticeably faster on 27.239 - repositories of even fairly modest size. Better yet, the bigger 27.240 - your repository is, the greater a performance advantage you'll 27.241 - see. The <literal role="hg-ext">inotify</literal> daemon makes 27.242 - status operations almost instantaneous on repositories of all 27.243 - sizes!</para> 27.244 - 27.245 - <para id="x_51f">If you like, you can manually start a status daemon using 27.246 - the <command role="hg-ext-inotify">inserve</command> command. 27.247 - This gives you slightly finer control over how the daemon ought 27.248 - to run. This command will of course only be available when the 27.249 - <literal role="hg-ext">inotify</literal> extension is 27.250 - enabled.</para> 27.251 - 27.252 - <para id="x_520">When you're using the <literal 27.253 - role="hg-ext">inotify</literal> extension, you should notice 27.254 - <emphasis>no difference at all</emphasis> in Mercurial's 27.255 - behavior, with the sole exception of status-related commands 27.256 - running a whole lot faster than they used to. You should 27.257 - specifically expect that commands will not print different 27.258 - output; neither should they give different results. If either of 27.259 - these situations occurs, please report a bug.</para> 27.260 - 27.261 - </sect1> 27.262 - <sect1 id="sec:hgext:extdiff"> 27.263 - <title>Flexible diff support with the <literal 27.264 - role="hg-ext">extdiff</literal> extension</title> 27.265 - 27.266 - <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg 27.267 - diff</command> command outputs plaintext unified diffs.</para> 27.268 - 27.269 - &interaction.extdiff.diff; 27.270 - 27.271 - <para id="x_522">If you would like to use an external tool to display 27.272 - modifications, you'll want to use the <literal 27.273 - role="hg-ext">extdiff</literal> extension. This will let you 27.274 - use, for example, a graphical diff tool.</para> 27.275 - 27.276 - <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is 27.277 - bundled with Mercurial, so it's easy to set up. In the <literal 27.278 - role="rc-extensions">extensions</literal> section of your 27.279 - <filename role="special">~/.hgrc</filename>, simply add a 27.280 - one-line entry to enable the extension.</para> 27.281 - <programlisting>[extensions] 27.282 -extdiff =</programlisting> 27.283 - <para id="x_524">This introduces a command named <command 27.284 - role="hg-ext-extdiff">extdiff</command>, which by default uses 27.285 - your system's <command>diff</command> command to generate a 27.286 - unified diff in the same form as the built-in <command 27.287 - role="hg-cmd">hg diff</command> command.</para> 27.288 - 27.289 - &interaction.extdiff.extdiff; 27.290 - 27.291 - <para id="x_525">The result won't be exactly the same as with the built-in 27.292 - <command role="hg-cmd">hg diff</command> variations, because the 27.293 - output of <command>diff</command> varies from one system to 27.294 - another, even when passed the same options.</para> 27.295 - 27.296 - <para id="x_526">As the <quote><literal>making snapshot</literal></quote> 27.297 - lines of output above imply, the <command 27.298 - role="hg-ext-extdiff">extdiff</command> command works by 27.299 - creating two snapshots of your source tree. The first snapshot 27.300 - is of the source revision; the second, of the target revision or 27.301 - working directory. The <command 27.302 - role="hg-ext-extdiff">extdiff</command> command generates 27.303 - these snapshots in a temporary directory, passes the name of 27.304 - each directory to an external diff viewer, then deletes the 27.305 - temporary directory. For efficiency, it only snapshots the 27.306 - directories and files that have changed between the two 27.307 - revisions.</para> 27.308 - 27.309 - <para id="x_527">Snapshot directory names have the same base name as your 27.310 - repository. If your repository path is <filename 27.311 - class="directory">/quux/bar/foo</filename>, then <filename 27.312 - class="directory">foo</filename> will be the name of each 27.313 - snapshot directory. Each snapshot directory name has its 27.314 - changeset ID appended, if appropriate. If a snapshot is of 27.315 - revision <literal>a631aca1083f</literal>, the directory will be 27.316 - named <filename class="directory">foo.a631aca1083f</filename>. 27.317 - A snapshot of the working directory won't have a changeset ID 27.318 - appended, so it would just be <filename 27.319 - class="directory">foo</filename> in this example. To see what 27.320 - this looks like in practice, look again at the <command 27.321 - role="hg-ext-extdiff">extdiff</command> example above. Notice 27.322 - that the diff has the snapshot directory names embedded in its 27.323 - header.</para> 27.324 - 27.325 - <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command 27.326 - accepts two important options. The <option 27.327 - role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option 27.328 - lets you choose a program to view differences with, instead of 27.329 - <command>diff</command>. With the <option 27.330 - role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option, 27.331 - you can change the options that <command 27.332 - role="hg-ext-extdiff">extdiff</command> passes to the program 27.333 - (by default, these options are 27.334 - <quote><literal>-Npru</literal></quote>, which only make sense 27.335 - if you're running <command>diff</command>). In other respects, 27.336 - the <command role="hg-ext-extdiff">extdiff</command> command 27.337 - acts similarly to the built-in <command role="hg-cmd">hg 27.338 - diff</command> command: you use the same option names, syntax, 27.339 - and arguments to specify the revisions you want, the files you 27.340 - want, and so on.</para> 27.341 - 27.342 - <para id="x_529">As an example, here's how to run the normal system 27.343 - <command>diff</command> command, getting it to generate context 27.344 - diffs (using the <option role="cmd-opt-diff">-c</option> option) 27.345 - instead of unified diffs, and five lines of context instead of 27.346 - the default three (passing <literal>5</literal> as the argument 27.347 - to the <option role="cmd-opt-diff">-C</option> option).</para> 27.348 - 27.349 - &interaction.extdiff.extdiff-ctx; 27.350 - 27.351 - <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to 27.352 - launch the <command>kdiff3</command> viewer.</para> 27.353 - <programlisting>hg extdiff -p kdiff3 -o</programlisting> 27.354 - 27.355 - <para id="x_52b">If your diff viewing command can't deal with directories, 27.356 - you can easily work around this with a little scripting. For an 27.357 - example of such scripting in action with the <literal 27.358 - role="hg-ext">mq</literal> extension and the 27.359 - <command>interdiff</command> command, see <xref 27.360 - linkend="mq-collab:tips:interdiff"/>.</para> 27.361 - 27.362 - <sect2> 27.363 - <title>Defining command aliases</title> 27.364 - 27.365 - <para id="x_52c">It can be cumbersome to remember the options to both the 27.366 - <command role="hg-ext-extdiff">extdiff</command> command and 27.367 - the diff viewer you want to use, so the <literal 27.368 - role="hg-ext">extdiff</literal> extension lets you define 27.369 - <emphasis>new</emphasis> commands that will invoke your diff 27.370 - viewer with exactly the right options.</para> 27.371 - 27.372 - <para id="x_52d">All you need to do is edit your <filename 27.373 - role="special">~/.hgrc</filename>, and add a section named 27.374 - <literal role="rc-extdiff">extdiff</literal>. Inside this 27.375 - section, you can define multiple commands. Here's how to add 27.376 - a <literal>kdiff3</literal> command. Once you've defined 27.377 - this, you can type <quote><literal>hg kdiff3</literal></quote> 27.378 - and the <literal role="hg-ext">extdiff</literal> extension 27.379 - will run <command>kdiff3</command> for you.</para> 27.380 - <programlisting>[extdiff] 27.381 -cmd.kdiff3 =</programlisting> 27.382 - <para id="x_52e">If you leave the right hand side of the definition empty, 27.383 - as above, the <literal role="hg-ext">extdiff</literal> 27.384 - extension uses the name of the command you defined as the name 27.385 - of the external program to run. But these names don't have to 27.386 - be the same. Here, we define a command named 27.387 - <quote><literal>hg wibble</literal></quote>, which runs 27.388 - <command>kdiff3</command>.</para> 27.389 - <programlisting>[extdiff] 27.390 - cmd.wibble = kdiff3</programlisting> 27.391 - 27.392 - <para id="x_52f">You can also specify the default options that you want to 27.393 - invoke your diff viewing program with. The prefix to use is 27.394 - <quote><literal>opts.</literal></quote>, followed by the name 27.395 - of the command to which the options apply. This example 27.396 - defines a <quote><literal>hg vimdiff</literal></quote> command 27.397 - that runs the <command>vim</command> editor's 27.398 - <literal>DirDiff</literal> extension.</para> 27.399 - <programlisting>[extdiff] 27.400 - cmd.vimdiff = vim 27.401 -opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting> 27.402 - 27.403 - </sect2> 27.404 - </sect1> 27.405 - <sect1 id="sec:hgext:transplant"> 27.406 - <title>Cherrypicking changes with the <literal 27.407 - role="hg-ext">transplant</literal> extension</title> 27.408 - 27.409 - <para id="x_530">Need to have a long chat with Brendan about this.</para> 27.410 - 27.411 - </sect1> 27.412 - <sect1 id="sec:hgext:patchbomb"> 27.413 - <title>Send changes via email with the <literal 27.414 - role="hg-ext">patchbomb</literal> extension</title> 27.415 - 27.416 - <para id="x_531">Many projects have a culture of <quote>change 27.417 - review</quote>, in which people send their modifications to a 27.418 - mailing list for others to read and comment on before they 27.419 - commit the final version to a shared repository. Some projects 27.420 - have people who act as gatekeepers; they apply changes from 27.421 - other people to a repository to which those others don't have 27.422 - access.</para> 27.423 - 27.424 - <para id="x_532">Mercurial makes it easy to send changes over email for 27.425 - review or application, via its <literal 27.426 - role="hg-ext">patchbomb</literal> extension. The extension is 27.427 - so named because changes are formatted as patches, and it's usual 27.428 - to send one changeset per email message. Sending a long series 27.429 - of changes by email is thus much like <quote>bombing</quote> the 27.430 - recipient's inbox, hence <quote>patchbomb</quote>.</para> 27.431 - 27.432 - <para id="x_533">As usual, the basic configuration of the <literal 27.433 - role="hg-ext">patchbomb</literal> extension takes just one or 27.434 - two lines in your <filename role="special"> 27.435 - /.hgrc</filename>.</para> 27.436 - <programlisting>[extensions] 27.437 -patchbomb =</programlisting> 27.438 - <para id="x_534">Once you've enabled the extension, you will have a new 27.439 - command available, named <command 27.440 - role="hg-ext-patchbomb">email</command>.</para> 27.441 - 27.442 - <para id="x_535">The safest and best way to invoke the <command 27.443 - role="hg-ext-patchbomb">email</command> command is to 27.444 - <emphasis>always</emphasis> run it first with the <option 27.445 - role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option. 27.446 - This will show you what the command <emphasis>would</emphasis> 27.447 - send, without actually sending anything. Once you've had a 27.448 - quick glance over the changes and verified that you are sending 27.449 - the right ones, you can rerun the same command, with the <option 27.450 - role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option 27.451 - removed.</para> 27.452 - 27.453 - <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command 27.454 - accepts the same kind of revision syntax as every other 27.455 - Mercurial command. For example, this command will send every 27.456 - revision between 7 and <literal>tip</literal>, inclusive.</para> 27.457 - <programlisting>hg email -n 7:tip</programlisting> 27.458 - <para id="x_537">You can also specify a <emphasis>repository</emphasis> to 27.459 - compare with. If you provide a repository but no revisions, the 27.460 - <command role="hg-ext-patchbomb">email</command> command will 27.461 - send all revisions in the local repository that are not present 27.462 - in the remote repository. If you additionally specify revisions 27.463 - or a branch name (the latter using the <option 27.464 - role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option), 27.465 - this will constrain the revisions sent.</para> 27.466 - 27.467 - <para id="x_538">It's perfectly safe to run the <command 27.468 - role="hg-ext-patchbomb">email</command> command without the 27.469 - names of the people you want to send to: if you do this, it will 27.470 - just prompt you for those values interactively. (If you're 27.471 - using a Linux or Unix-like system, you should have enhanced 27.472 - <literal>readline</literal>-style editing capabilities when 27.473 - entering those headers, too, which is useful.)</para> 27.474 - 27.475 - <para id="x_539">When you are sending just one revision, the <command 27.476 - role="hg-ext-patchbomb">email</command> command will by 27.477 - default use the first line of the changeset description as the 27.478 - subject of the single email message it sends.</para> 27.479 - 27.480 - <para id="x_53a">If you send multiple revisions, the <command 27.481 - role="hg-ext-patchbomb">email</command> command will usually 27.482 - send one message per changeset. It will preface the series with 27.483 - an introductory message, in which you should describe the 27.484 - purpose of the series of changes you're sending.</para> 27.485 - 27.486 - <sect2> 27.487 - <title>Changing the behavior of patchbombs</title> 27.488 - 27.489 - <para id="x_53b">Not every project has exactly the same conventions for 27.490 - sending changes in email; the <literal 27.491 - role="hg-ext">patchbomb</literal> extension tries to 27.492 - accommodate a number of variations through command line 27.493 - options.</para> 27.494 - <itemizedlist> 27.495 - <listitem><para id="x_53c">You can write a subject for the introductory 27.496 - message on the command line using the <option 27.497 - role="hg-ext-patchbomb-cmd-email-opt">hg -s</option> 27.498 - option. This takes one argument, the text of the subject 27.499 - to use.</para> 27.500 - </listitem> 27.501 - <listitem><para id="x_53d">To change the email address from which the 27.502 - messages originate, use the <option 27.503 - role="hg-ext-patchbomb-cmd-email-opt">hg -f</option> 27.504 - option. This takes one argument, the email address to 27.505 - use.</para> 27.506 - </listitem> 27.507 - <listitem><para id="x_53e">The default behavior is to send unified diffs 27.508 - (see <xref linkend="sec:mq:patch"/> for a 27.509 - description of the 27.510 - format), one per message. You can send a binary bundle 27.511 - instead with the <option 27.512 - role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> 27.513 - option.</para> 27.514 - </listitem> 27.515 - <listitem><para id="x_53f">Unified diffs are normally prefaced with a 27.516 - metadata header. You can omit this, and send unadorned 27.517 - diffs, with the <option 27.518 - role="hg-ext-patchbomb-cmd-email-opt">hg 27.519 - --plain</option> option.</para> 27.520 - </listitem> 27.521 - <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>, 27.522 - in the same body part as the description of a patch. This 27.523 - makes it easiest for the largest number of readers to 27.524 - quote and respond to parts of a diff, as some mail clients 27.525 - will only quote the first MIME body part in a message. If 27.526 - you'd prefer to send the description and the diff in 27.527 - separate body parts, use the <option 27.528 - role="hg-ext-patchbomb-cmd-email-opt">hg -a</option> 27.529 - option.</para> 27.530 - </listitem> 27.531 - <listitem><para id="x_541">Instead of sending mail messages, you can 27.532 - write them to an <literal>mbox</literal>-format mail 27.533 - folder using the <option 27.534 - role="hg-ext-patchbomb-cmd-email-opt">hg -m</option> 27.535 - option. That option takes one argument, the name of the 27.536 - file to write to.</para> 27.537 - </listitem> 27.538 - <listitem><para id="x_542">If you would like to add a 27.539 - <command>diffstat</command>-format summary to each patch, 27.540 - and one to the introductory message, use the <option 27.541 - role="hg-ext-patchbomb-cmd-email-opt">hg -d</option> 27.542 - option. The <command>diffstat</command> command displays 27.543 - a table containing the name of each file patched, the 27.544 - number of lines affected, and a histogram showing how much 27.545 - each file is modified. This gives readers a qualitative 27.546 - glance at how complex a patch is.</para> 27.547 - </listitem></itemizedlist> 27.548 - 27.549 - </sect2> 27.550 - </sect1> 27.551 -</chapter> 27.552 - 27.553 -<!-- 27.554 -local variables: 27.555 -sgml-parent-document: ("00book.xml" "book" "chapter") 27.556 -end: 27.557 --->
28.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 28.2 +++ b/en/ch13-mq-collab.xml Thu May 07 21:07:35 2009 -0700 28.3 @@ -0,0 +1,518 @@ 28.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 28.5 + 28.6 +<chapter id="chap:mq-collab"> 28.7 + <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?> 28.8 + <title>Advanced uses of Mercurial Queues</title> 28.9 + 28.10 + <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial 28.11 + Queues, use of a little discipline and some of MQ's less 28.12 + frequently used capabilities makes it possible to work in 28.13 + complicated development environments.</para> 28.14 + 28.15 + <para id="x_15e">In this chapter, I will use as an example a technique I have 28.16 + used to manage the development of an Infiniband device driver for 28.17 + the Linux kernel. The driver in question is large (at least as 28.18 + drivers go), with 25,000 lines of code spread across 35 source 28.19 + files. It is maintained by a small team of developers.</para> 28.20 + 28.21 + <para id="x_15f">While much of the material in this chapter is specific to 28.22 + Linux, the same principles apply to any code base for which you're 28.23 + not the primary owner, and upon which you need to do a lot of 28.24 + development.</para> 28.25 + 28.26 + <sect1> 28.27 + <title>The problem of many targets</title> 28.28 + 28.29 + <para id="x_160">The Linux kernel changes rapidly, and has never been 28.30 + internally stable; developers frequently make drastic changes 28.31 + between releases. This means that a version of the driver that 28.32 + works well with a particular released version of the kernel will 28.33 + not even <emphasis>compile</emphasis> correctly against, 28.34 + typically, any other version.</para> 28.35 + 28.36 + <para id="x_161">To maintain a driver, we have to keep a number of distinct 28.37 + versions of Linux in mind.</para> 28.38 + <itemizedlist> 28.39 + <listitem><para id="x_162">One target is the main Linux kernel development 28.40 + tree. Maintenance of the code is in this case partly shared 28.41 + by other developers in the kernel community, who make 28.42 + <quote>drive-by</quote> modifications to the driver as they 28.43 + develop and refine kernel subsystems.</para> 28.44 + </listitem> 28.45 + <listitem><para id="x_163">We also maintain a number of 28.46 + <quote>backports</quote> to older versions of the Linux 28.47 + kernel, to support the needs of customers who are running 28.48 + older Linux distributions that do not incorporate our 28.49 + drivers. (To <emphasis>backport</emphasis> a piece of code 28.50 + is to modify it to work in an older version of its target 28.51 + environment than the version it was developed for.)</para> 28.52 + </listitem> 28.53 + <listitem><para id="x_164">Finally, we make software releases on a schedule 28.54 + that is necessarily not aligned with those used by Linux 28.55 + distributors and kernel developers, so that we can deliver 28.56 + new features to customers without forcing them to upgrade 28.57 + their entire kernels or distributions.</para> 28.58 + </listitem></itemizedlist> 28.59 + 28.60 + <sect2> 28.61 + <title>Tempting approaches that don't work well</title> 28.62 + 28.63 + <para id="x_165">There are two <quote>standard</quote> ways to maintain a 28.64 + piece of software that has to target many different 28.65 + environments.</para> 28.66 + 28.67 + <para id="x_166">The first is to maintain a number of branches, each 28.68 + intended for a single target. The trouble with this approach 28.69 + is that you must maintain iron discipline in the flow of 28.70 + changes between repositories. A new feature or bug fix must 28.71 + start life in a <quote>pristine</quote> repository, then 28.72 + percolate out to every backport repository. Backport changes 28.73 + are more limited in the branches they should propagate to; a 28.74 + backport change that is applied to a branch where it doesn't 28.75 + belong will probably stop the driver from compiling.</para> 28.76 + 28.77 + <para id="x_167">The second is to maintain a single source tree filled with 28.78 + conditional statements that turn chunks of code on or off 28.79 + depending on the intended target. Because these 28.80 + <quote>ifdefs</quote> are not allowed in the Linux kernel 28.81 + tree, a manual or automatic process must be followed to strip 28.82 + them out and yield a clean tree. A code base maintained in 28.83 + this fashion rapidly becomes a rat's nest of conditional 28.84 + blocks that are difficult to understand and maintain.</para> 28.85 + 28.86 + <para id="x_168">Neither of these approaches is well suited to a situation 28.87 + where you don't <quote>own</quote> the canonical copy of a 28.88 + source tree. In the case of a Linux driver that is 28.89 + distributed with the standard kernel, Linus's tree contains 28.90 + the copy of the code that will be treated by the world as 28.91 + canonical. The upstream version of <quote>my</quote> driver 28.92 + can be modified by people I don't know, without me even 28.93 + finding out about it until after the changes show up in 28.94 + Linus's tree.</para> 28.95 + 28.96 + <para id="x_169">These approaches have the added weakness of making it 28.97 + difficult to generate well-formed patches to submit 28.98 + upstream.</para> 28.99 + 28.100 + <para id="x_16a">In principle, Mercurial Queues seems like a good candidate 28.101 + to manage a development scenario such as the above. While 28.102 + this is indeed the case, MQ contains a few added features that 28.103 + make the job more pleasant.</para> 28.104 + 28.105 + </sect2> 28.106 + </sect1> 28.107 + <sect1> 28.108 + <title>Conditionally applying patches with guards</title> 28.109 + 28.110 + <para id="x_16b">Perhaps the best way to maintain sanity with so many targets 28.111 + is to be able to choose specific patches to apply for a given 28.112 + situation. MQ provides a feature called <quote>guards</quote> 28.113 + (which originates with quilt's <literal>guards</literal> 28.114 + command) that does just this. To start off, let's create a 28.115 + simple repository for experimenting in.</para> 28.116 + 28.117 + &interaction.mq.guards.init; 28.118 + 28.119 + <para id="x_16c">This gives us a tiny repository that contains two patches 28.120 + that don't have any dependencies on each other, because they 28.121 + touch different files.</para> 28.122 + 28.123 + <para id="x_16d">The idea behind conditional application is that you can 28.124 + <quote>tag</quote> a patch with a <emphasis>guard</emphasis>, 28.125 + which is simply a text string of your choosing, then tell MQ to 28.126 + select specific guards to use when applying patches. MQ will 28.127 + then either apply, or skip over, a guarded patch, depending on 28.128 + the guards that you have selected.</para> 28.129 + 28.130 + <para id="x_16e">A patch can have an arbitrary number of guards; each one is 28.131 + <emphasis>positive</emphasis> (<quote>apply this patch if this 28.132 + guard is selected</quote>) or <emphasis>negative</emphasis> 28.133 + (<quote>skip this patch if this guard is selected</quote>). A 28.134 + patch with no guards is always applied.</para> 28.135 + 28.136 + </sect1> 28.137 + <sect1> 28.138 + <title>Controlling the guards on a patch</title> 28.139 + 28.140 + <para id="x_16f">The <command role="hg-ext-mq">qguard</command> command lets 28.141 + you determine which guards should apply to a patch, or display 28.142 + the guards that are already in effect. Without any arguments, it 28.143 + displays the guards on the current topmost patch.</para> 28.144 + 28.145 + &interaction.mq.guards.qguard; 28.146 + 28.147 + <para id="x_170">To set a positive guard on a patch, prefix the name of the 28.148 + guard with a <quote><literal>+</literal></quote>.</para> 28.149 + 28.150 + &interaction.mq.guards.qguard.pos; 28.151 + 28.152 + <para id="x_171">To set a negative guard 28.153 + on a patch, prefix the name of the guard with a 28.154 + <quote><literal>-</literal></quote>.</para> 28.155 + 28.156 + &interaction.mq.guards.qguard.neg; 28.157 + 28.158 + <note> 28.159 + <para id="x_172"> The <command role="hg-ext-mq">qguard</command> command 28.160 + <emphasis>sets</emphasis> the guards on a patch; it doesn't 28.161 + <emphasis>modify</emphasis> them. What this means is that if 28.162 + you run <command role="hg-cmd">hg qguard +a +b</command> on a 28.163 + patch, then <command role="hg-cmd">hg qguard +c</command> on 28.164 + the same patch, the <emphasis>only</emphasis> guard that will 28.165 + be set on it afterwards is <literal>+c</literal>.</para> 28.166 + </note> 28.167 + 28.168 + <para id="x_173">Mercurial stores guards in the <filename 28.169 + role="special">series</filename> file; the form in which they 28.170 + are stored is easy both to understand and to edit by hand. (In 28.171 + other words, you don't have to use the <command 28.172 + role="hg-ext-mq">qguard</command> command if you don't want 28.173 + to; it's okay to simply edit the <filename 28.174 + role="special">series</filename> file.)</para> 28.175 + 28.176 + &interaction.mq.guards.series; 28.177 + 28.178 + </sect1> 28.179 + <sect1> 28.180 + <title>Selecting the guards to use</title> 28.181 + 28.182 + <para id="x_174">The <command role="hg-ext-mq">qselect</command> command 28.183 + determines which guards are active at a given time. The effect 28.184 + of this is to determine which patches MQ will apply the next 28.185 + time you run <command role="hg-ext-mq">qpush</command>. It has 28.186 + no other effect; in particular, it doesn't do anything to 28.187 + patches that are already applied.</para> 28.188 + 28.189 + <para id="x_175">With no arguments, the <command 28.190 + role="hg-ext-mq">qselect</command> command lists the guards 28.191 + currently in effect, one per line of output. Each argument is 28.192 + treated as the name of a guard to apply.</para> 28.193 + 28.194 + &interaction.mq.guards.qselect.foo; 28.195 + 28.196 + <para id="x_176">In case you're interested, the currently selected guards are 28.197 + stored in the <filename role="special">guards</filename> file.</para> 28.198 + 28.199 + &interaction.mq.guards.qselect.cat; 28.200 + 28.201 + <para id="x_177">We can see the effect the selected guards have when we run 28.202 + <command role="hg-ext-mq">qpush</command>.</para> 28.203 + 28.204 + &interaction.mq.guards.qselect.qpush; 28.205 + 28.206 + <para id="x_178">A guard cannot start with a 28.207 + <quote><literal>+</literal></quote> or 28.208 + <quote><literal>-</literal></quote> character. The name of a 28.209 + guard must not contain white space, but most other characters 28.210 + are acceptable. If you try to use a guard with an invalid name, 28.211 + MQ will complain:</para> 28.212 + 28.213 + &interaction.mq.guards.qselect.error; 28.214 + 28.215 + <para id="x_179">Changing the selected guards changes the patches that are 28.216 + applied.</para> 28.217 + 28.218 + &interaction.mq.guards.qselect.quux; 28.219 + 28.220 + <para id="x_17a">You can see in the example below that negative guards take 28.221 + precedence over positive guards.</para> 28.222 + 28.223 + &interaction.mq.guards.qselect.foobar; 28.224 + 28.225 + </sect1> 28.226 + <sect1> 28.227 + <title>MQ's rules for applying patches</title> 28.228 + 28.229 + <para id="x_17b">The rules that MQ uses when deciding whether to apply a 28.230 + patch are as follows.</para> 28.231 + <itemizedlist> 28.232 + <listitem><para id="x_17c">A patch that has no guards is always 28.233 + applied.</para> 28.234 + </listitem> 28.235 + <listitem><para id="x_17d">If the patch has any negative guard that matches 28.236 + any currently selected guard, the patch is skipped.</para> 28.237 + </listitem> 28.238 + <listitem><para id="x_17e">If the patch has any positive guard that matches 28.239 + any currently selected guard, the patch is applied.</para> 28.240 + </listitem> 28.241 + <listitem><para id="x_17f">If the patch has positive or negative guards, 28.242 + but none matches any currently selected guard, the patch is 28.243 + skipped.</para> 28.244 + </listitem></itemizedlist> 28.245 + 28.246 + </sect1> 28.247 + <sect1> 28.248 + <title>Trimming the work environment</title> 28.249 + 28.250 + <para id="x_180">In working on the device driver I mentioned earlier, I don't 28.251 + apply the patches to a normal Linux kernel tree. Instead, I use 28.252 + a repository that contains only a snapshot of the source files 28.253 + and headers that are relevant to Infiniband development. This 28.254 + repository is 1% the size of a kernel repository, so it's easier 28.255 + to work with.</para> 28.256 + 28.257 + <para id="x_181">I then choose a <quote>base</quote> version on top of which 28.258 + the patches are applied. This is a snapshot of the Linux kernel 28.259 + tree as of a revision of my choosing. When I take the snapshot, 28.260 + I record the changeset ID from the kernel repository in the 28.261 + commit message. Since the snapshot preserves the 28.262 + <quote>shape</quote> and content of the relevant parts of the 28.263 + kernel tree, I can apply my patches on top of either my tiny 28.264 + repository or a normal kernel tree.</para> 28.265 + 28.266 + <para id="x_182">Normally, the base tree atop which the patches apply should 28.267 + be a snapshot of a very recent upstream tree. This best 28.268 + facilitates the development of patches that can easily be 28.269 + submitted upstream with few or no modifications.</para> 28.270 + 28.271 + </sect1> 28.272 + <sect1> 28.273 + <title>Dividing up the <filename role="special">series</filename> 28.274 + file</title> 28.275 + 28.276 + <para id="x_183">I categorise the patches in the <filename 28.277 + role="special">series</filename> file into a number of logical 28.278 + groups. Each section of like patches begins with a block of 28.279 + comments that describes the purpose of the patches that 28.280 + follow.</para> 28.281 + 28.282 + <para id="x_184">The sequence of patch groups that I maintain follows. The 28.283 + ordering of these groups is important; I'll describe why after I 28.284 + introduce the groups.</para> 28.285 + <itemizedlist> 28.286 + <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that 28.287 + the development team has submitted to the maintainer of the 28.288 + Infiniband subsystem, and which he has accepted, but which 28.289 + are not present in the snapshot that the tiny repository is 28.290 + based on. These are <quote>read only</quote> patches, 28.291 + present only to transform the tree into a similar state as 28.292 + it is in the upstream maintainer's repository.</para> 28.293 + </listitem> 28.294 + <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I 28.295 + have submitted, but that the upstream maintainer has 28.296 + requested modifications to before he will accept 28.297 + them.</para> 28.298 + </listitem> 28.299 + <listitem><para id="x_187">The <quote>pending</quote> group. Patches that 28.300 + I have not yet submitted to the upstream maintainer, but 28.301 + which we have finished working on. These will be <quote>read 28.302 + only</quote> for a while. If the upstream maintainer 28.303 + accepts them upon submission, I'll move them to the end of 28.304 + the <quote>accepted</quote> group. If he requests that I 28.305 + modify any, I'll move them to the beginning of the 28.306 + <quote>rework</quote> group.</para> 28.307 + </listitem> 28.308 + <listitem><para id="x_188">The <quote>in progress</quote> group. Patches 28.309 + that are actively being developed, and should not be 28.310 + submitted anywhere yet.</para> 28.311 + </listitem> 28.312 + <listitem><para id="x_189">The <quote>backport</quote> group. Patches that 28.313 + adapt the source tree to older versions of the kernel 28.314 + tree.</para> 28.315 + </listitem> 28.316 + <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches 28.317 + that for some reason should never be submitted upstream. 28.318 + For example, one such patch might change embedded driver 28.319 + identification strings to make it easier to distinguish, in 28.320 + the field, between an out-of-tree version of the driver and 28.321 + a version shipped by a distribution vendor.</para> 28.322 + </listitem></itemizedlist> 28.323 + 28.324 + <para id="x_18b">Now to return to the reasons for ordering groups of patches 28.325 + in this way. We would like the lowest patches in the stack to 28.326 + be as stable as possible, so that we will not need to rework 28.327 + higher patches due to changes in context. Putting patches that 28.328 + will never be changed first in the <filename 28.329 + role="special">series</filename> file serves this 28.330 + purpose.</para> 28.331 + 28.332 + <para id="x_18c">We would also like the patches that we know we'll need to 28.333 + modify to be applied on top of a source tree that resembles the 28.334 + upstream tree as closely as possible. This is why we keep 28.335 + accepted patches around for a while.</para> 28.336 + 28.337 + <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote> 28.338 + patches float at the end of the <filename 28.339 + role="special">series</filename> file. The backport patches 28.340 + must be applied on top of all other patches, and the <quote>do 28.341 + not ship</quote> patches might as well stay out of harm's 28.342 + way.</para> 28.343 + 28.344 + </sect1> 28.345 + <sect1> 28.346 + <title>Maintaining the patch series</title> 28.347 + 28.348 + <para id="x_18e">In my work, I use a number of guards to control which 28.349 + patches are to be applied.</para> 28.350 + 28.351 + <itemizedlist> 28.352 + <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with 28.353 + <literal>accepted</literal>. I enable this guard most of 28.354 + the time. When I'm applying the patches on top of a tree 28.355 + where the patches are already present, I can turn this patch 28.356 + off, and the patches that follow it will apply 28.357 + cleanly.</para> 28.358 + </listitem> 28.359 + <listitem><para id="x_190">Patches that are <quote>finished</quote>, but 28.360 + not yet submitted, have no guards. If I'm applying the 28.361 + patch stack to a copy of the upstream tree, I don't need to 28.362 + enable any guards in order to get a reasonably safe source 28.363 + tree.</para> 28.364 + </listitem> 28.365 + <listitem><para id="x_191">Those patches that need reworking before being 28.366 + resubmitted are guarded with 28.367 + <literal>rework</literal>.</para> 28.368 + </listitem> 28.369 + <listitem><para id="x_192">For those patches that are still under 28.370 + development, I use <literal>devel</literal>.</para> 28.371 + </listitem> 28.372 + <listitem><para id="x_193">A backport patch may have several guards, one 28.373 + for each version of the kernel to which it applies. For 28.374 + example, a patch that backports a piece of code to 2.6.9 28.375 + will have a <literal>2.6.9</literal> guard.</para> 28.376 + </listitem></itemizedlist> 28.377 + <para id="x_194">This variety of guards gives me considerable flexibility in 28.378 + determining what kind of source tree I want to end up with. For 28.379 + most situations, the selection of appropriate guards is 28.380 + automated during the build process, but I can manually tune the 28.381 + guards to use for less common circumstances.</para> 28.382 + 28.383 + <sect2> 28.384 + <title>The art of writing backport patches</title> 28.385 + 28.386 + <para id="x_195">Using MQ, writing a backport patch is a simple process. 28.387 + All such a patch has to do is modify a piece of code that uses 28.388 + a kernel feature not present in the older version of the 28.389 + kernel, so that the driver continues to work correctly under 28.390 + that older version.</para> 28.391 + 28.392 + <para id="x_196">A useful goal when writing a good backport patch is to 28.393 + make your code look as if it was written for the older version 28.394 + of the kernel you're targeting. The less obtrusive the patch, 28.395 + the easier it will be to understand and maintain. If you're 28.396 + writing a collection of backport patches to avoid the 28.397 + <quote>rat's nest</quote> effect of lots of 28.398 + <literal>#ifdef</literal>s (hunks of source code that are only 28.399 + used conditionally) in your code, don't introduce 28.400 + version-dependent <literal>#ifdef</literal>s into the patches. 28.401 + Instead, write several patches, each of which makes 28.402 + unconditional changes, and control their application using 28.403 + guards.</para> 28.404 + 28.405 + <para id="x_197">There are two reasons to divide backport patches into a 28.406 + distinct group, away from the <quote>regular</quote> patches 28.407 + whose effects they modify. The first is that intermingling the 28.408 + two makes it more difficult to use a tool like the <literal 28.409 + role="hg-ext">patchbomb</literal> extension to automate the 28.410 + process of submitting the patches to an upstream maintainer. 28.411 + The second is that a backport patch could perturb the context 28.412 + in which a subsequent regular patch is applied, making it 28.413 + impossible to apply the regular patch cleanly 28.414 + <emphasis>without</emphasis> the earlier backport patch 28.415 + already being applied.</para> 28.416 + 28.417 + </sect2> 28.418 + </sect1> 28.419 + <sect1> 28.420 + <title>Useful tips for developing with MQ</title> 28.421 + 28.422 + <sect2> 28.423 + <title>Organising patches in directories</title> 28.424 + 28.425 + <para id="x_198">If you're working on a substantial project with MQ, it's 28.426 + not difficult to accumulate a large number of patches. For 28.427 + example, I have one patch repository that contains over 250 28.428 + patches.</para> 28.429 + 28.430 + <para id="x_199">If you can group these patches into separate logical 28.431 + categories, you can if you like store them in different 28.432 + directories; MQ has no problems with patch names that contain 28.433 + path separators.</para> 28.434 + 28.435 + </sect2> 28.436 + <sect2 id="mq-collab:tips:interdiff"> 28.437 + <title>Viewing the history of a patch</title> 28.438 + 28.439 + <para id="x_19a">If you're developing a set of patches over a long time, 28.440 + it's a good idea to maintain them in a repository, as 28.441 + discussed in <xref linkend="sec:mq:repo"/>. If you do 28.442 + so, you'll quickly 28.443 + discover that using the <command role="hg-cmd">hg 28.444 + diff</command> command to look at the history of changes to 28.445 + a patch is unworkable. This is in part because you're looking 28.446 + at the second derivative of the real code (a diff of a diff), 28.447 + but also because MQ adds noise to the process by modifying 28.448 + time stamps and directory names when it updates a 28.449 + patch.</para> 28.450 + 28.451 + <para id="x_19b">However, you can use the <literal 28.452 + role="hg-ext">extdiff</literal> extension, which is bundled 28.453 + with Mercurial, to turn a diff of two versions of a patch into 28.454 + something readable. To do this, you will need a third-party 28.455 + package called <literal role="package">patchutils</literal> 28.456 + <citation>web:patchutils</citation>. This provides a command 28.457 + named <command>interdiff</command>, which shows the 28.458 + differences between two diffs as a diff. Used on two versions 28.459 + of the same diff, it generates a diff that represents the diff 28.460 + from the first to the second version.</para> 28.461 + 28.462 + <para id="x_19c">You can enable the <literal 28.463 + role="hg-ext">extdiff</literal> extension in the usual way, 28.464 + by adding a line to the <literal 28.465 + role="rc-extensions">extensions</literal> section of your 28.466 + <filename role="special">~/.hgrc</filename>.</para> 28.467 + <programlisting>[extensions] 28.468 +extdiff =</programlisting> 28.469 + <para id="x_19d">The <command>interdiff</command> command expects to be 28.470 + passed the names of two files, but the <literal 28.471 + role="hg-ext">extdiff</literal> extension passes the program 28.472 + it runs a pair of directories, each of which can contain an 28.473 + arbitrary number of files. We thus need a small program that 28.474 + will run <command>interdiff</command> on each pair of files in 28.475 + these two directories. This program is available as <filename 28.476 + role="special">hg-interdiff</filename> in the <filename 28.477 + class="directory">examples</filename> directory of the 28.478 + source code repository that accompanies this book. <!-- 28.479 + &example.hg-interdiff; --></para> 28.480 + 28.481 + <para id="x_19e">With the <filename role="special">hg-interdiff</filename> 28.482 + program in your shell's search path, you can run it as 28.483 + follows, from inside an MQ patch directory:</para> 28.484 + <programlisting>hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting> 28.485 + <para id="x_19f">Since you'll probably want to use this long-winded command 28.486 + a lot, you can get <literal role="hg-ext">hgext</literal> to 28.487 + make it available as a normal Mercurial command, again by 28.488 + editing your <filename 28.489 + role="special">~/.hgrc</filename>.</para> 28.490 + <programlisting>[extdiff] 28.491 +cmd.interdiff = hg-interdiff</programlisting> 28.492 + <para id="x_1a0">This directs <literal role="hg-ext">hgext</literal> to 28.493 + make an <literal>interdiff</literal> command available, so you 28.494 + can now shorten the previous invocation of <command 28.495 + role="hg-ext-extdiff">extdiff</command> to something a 28.496 + little more wieldy.</para> 28.497 + <programlisting>hg interdiff -r A:B my-change.patch</programlisting> 28.498 + 28.499 + <note> 28.500 + <para id="x_1a1"> The <command>interdiff</command> command works well 28.501 + only if the underlying files against which versions of a 28.502 + patch are generated remain the same. If you create a patch, 28.503 + modify the underlying files, and then regenerate the patch, 28.504 + <command>interdiff</command> may not produce useful 28.505 + output.</para> 28.506 + </note> 28.507 + 28.508 + <para id="x_1a2">The <literal role="hg-ext">extdiff</literal> extension is 28.509 + useful for more than merely improving the presentation of MQ 28.510 + patches. To read more about it, go to <xref 28.511 + linkend="sec:hgext:extdiff"/>.</para> 28.512 + 28.513 + </sect2> 28.514 + </sect1> 28.515 +</chapter> 28.516 + 28.517 +<!-- 28.518 +local variables: 28.519 +sgml-parent-document: ("00book.xml" "book" "chapter") 28.520 +end: 28.521 +-->
29.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 29.2 +++ b/en/ch14-hgext.xml Thu May 07 21:07:35 2009 -0700 29.3 @@ -0,0 +1,554 @@ 29.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 29.5 + 29.6 +<chapter id="chap:hgext"> 29.7 + <?dbhtml filename="adding-functionality-with-extensions.html"?> 29.8 + <title>Adding functionality with extensions</title> 29.9 + 29.10 + <para id="x_4fe">While the core of Mercurial is quite complete from a 29.11 + functionality standpoint, it's deliberately shorn of fancy 29.12 + features. This approach of preserving simplicity keeps the 29.13 + software easy to deal with for both maintainers and users.</para> 29.14 + 29.15 + <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible 29.16 + command set: you can add features to it as 29.17 + <emphasis>extensions</emphasis> (sometimes known as 29.18 + <emphasis>plugins</emphasis>). We've already discussed a few of 29.19 + these extensions in earlier chapters.</para> 29.20 + <itemizedlist> 29.21 + <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/> 29.22 + covers the <literal role="hg-ext">fetch</literal> extension; 29.23 + this combines pulling new changes and merging them with local 29.24 + changes into a single command, <command 29.25 + role="hg-ext-fetch">fetch</command>.</para> 29.26 + </listitem> 29.27 + <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered 29.28 + several extensions that are useful for hook-related 29.29 + functionality: <literal role="hg-ext">acl</literal> adds 29.30 + access control lists; <literal 29.31 + role="hg-ext">bugzilla</literal> adds integration with the 29.32 + Bugzilla bug tracking system; and <literal 29.33 + role="hg-ext">notify</literal> sends notification emails on 29.34 + new changes.</para> 29.35 + </listitem> 29.36 + <listitem><para id="x_502">The Mercurial Queues patch management extension is 29.37 + so invaluable that it merits two chapters and an appendix all 29.38 + to itself. <xref linkend="chap:mq"/> covers the 29.39 + basics; <xref 29.40 + linkend="chap:mq-collab"/> discusses advanced topics; 29.41 + and <xref linkend="chap:mqref"/> goes into detail on 29.42 + each 29.43 + command.</para> 29.44 + </listitem></itemizedlist> 29.45 + 29.46 + <para id="x_503">In this chapter, we'll cover some of the other extensions that 29.47 + are available for Mercurial, and briefly touch on some of the 29.48 + machinery you'll need to know about if you want to write an 29.49 + extension of your own.</para> 29.50 + <itemizedlist> 29.51 + <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>, 29.52 + we'll discuss the possibility of <emphasis>huge</emphasis> 29.53 + performance improvements using the <literal 29.54 + role="hg-ext">inotify</literal> extension.</para> 29.55 + </listitem></itemizedlist> 29.56 + 29.57 + <sect1 id="sec:hgext:inotify"> 29.58 + <title>Improve performance with the <literal 29.59 + role="hg-ext">inotify</literal> extension</title> 29.60 + 29.61 + <para id="x_505">Are you interested in having some of the most common 29.62 + Mercurial operations run as much as a hundred times faster? 29.63 + Read on!</para> 29.64 + 29.65 + <para id="x_506">Mercurial has great performance under normal circumstances. 29.66 + For example, when you run the <command role="hg-cmd">hg 29.67 + status</command> command, Mercurial has to scan almost every 29.68 + directory and file in your repository so that it can display 29.69 + file status. Many other Mercurial commands need to do the same 29.70 + work behind the scenes; for example, the <command 29.71 + role="hg-cmd">hg diff</command> command uses the status 29.72 + machinery to avoid doing an expensive comparison operation on 29.73 + files that obviously haven't changed.</para> 29.74 + 29.75 + <para id="x_507">Because obtaining file status is crucial to good 29.76 + performance, the authors of Mercurial have optimised this code 29.77 + to within an inch of its life. However, there's no avoiding the 29.78 + fact that when you run <command role="hg-cmd">hg 29.79 + status</command>, Mercurial is going to have to perform at 29.80 + least one expensive system call for each managed file to 29.81 + determine whether it's changed since the last time Mercurial 29.82 + checked. For a sufficiently large repository, this can take a 29.83 + long time.</para> 29.84 + 29.85 + <para id="x_508">To put a number on the magnitude of this effect, I created a 29.86 + repository containing 150,000 managed files. I timed <command 29.87 + role="hg-cmd">hg status</command> as taking ten seconds to 29.88 + run, even when <emphasis>none</emphasis> of those files had been 29.89 + modified.</para> 29.90 + 29.91 + <para id="x_509">Many modern operating systems contain a file notification 29.92 + facility. If a program signs up to an appropriate service, the 29.93 + operating system will notify it every time a file of interest is 29.94 + created, modified, or deleted. On Linux systems, the kernel 29.95 + component that does this is called 29.96 + <literal>inotify</literal>.</para> 29.97 + 29.98 + <para id="x_50a">Mercurial's <literal role="hg-ext">inotify</literal> 29.99 + extension talks to the kernel's <literal>inotify</literal> 29.100 + component to optimise <command role="hg-cmd">hg status</command> 29.101 + commands. The extension has two components. A daemon sits in 29.102 + the background and receives notifications from the 29.103 + <literal>inotify</literal> subsystem. It also listens for 29.104 + connections from a regular Mercurial command. The extension 29.105 + modifies Mercurial's behavior so that instead of scanning the 29.106 + filesystem, it queries the daemon. Since the daemon has perfect 29.107 + information about the state of the repository, it can respond 29.108 + with a result instantaneously, avoiding the need to scan every 29.109 + directory and file in the repository.</para> 29.110 + 29.111 + <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as 29.112 + taking to run <command role="hg-cmd">hg status</command> on a 29.113 + 150,000 file repository. With the <literal 29.114 + role="hg-ext">inotify</literal> extension enabled, the time 29.115 + dropped to 0.1 seconds, a factor of <emphasis>one 29.116 + hundred</emphasis> faster.</para> 29.117 + 29.118 + <para id="x_50c">Before we continue, please pay attention to some 29.119 + caveats.</para> 29.120 + <itemizedlist> 29.121 + <listitem><para id="x_50d">The <literal role="hg-ext">inotify</literal> 29.122 + extension is Linux-specific. Because it interfaces directly 29.123 + to the Linux kernel's <literal>inotify</literal> subsystem, 29.124 + it does not work on other operating systems.</para> 29.125 + </listitem> 29.126 + <listitem><para id="x_50e">It should work on any Linux distribution that 29.127 + was released after early 2005. Older distributions are 29.128 + likely to have a kernel that lacks 29.129 + <literal>inotify</literal>, or a version of 29.130 + <literal>glibc</literal> that does not have the necessary 29.131 + interfacing support.</para> 29.132 + </listitem> 29.133 + <listitem><para id="x_50f">Not all filesystems are suitable for use with 29.134 + the <literal role="hg-ext">inotify</literal> extension. 29.135 + Network filesystems such as NFS are a non-starter, for 29.136 + example, particularly if you're running Mercurial on several 29.137 + systems, all mounting the same network filesystem. The 29.138 + kernel's <literal>inotify</literal> system has no way of 29.139 + knowing about changes made on another system. Most local 29.140 + filesystems (e.g. ext3, XFS, ReiserFS) should work 29.141 + fine.</para> 29.142 + </listitem></itemizedlist> 29.143 + 29.144 + <para id="x_510">The <literal role="hg-ext">inotify</literal> extension is 29.145 + not yet shipped with Mercurial as of May 2007, so it's a little 29.146 + more involved to set up than other extensions. But the 29.147 + performance improvement is worth it!</para> 29.148 + 29.149 + <para id="x_511">The extension currently comes in two parts: a set of patches 29.150 + to the Mercurial source code, and a library of Python bindings 29.151 + to the <literal>inotify</literal> subsystem.</para> 29.152 + <note> 29.153 + <para id="x_512"> There are <emphasis>two</emphasis> Python 29.154 + <literal>inotify</literal> binding libraries. One of them is 29.155 + called <literal>pyinotify</literal>, and is packaged by some 29.156 + Linux distributions as <literal>python-inotify</literal>. 29.157 + This is <emphasis>not</emphasis> the one you'll need, as it is 29.158 + too buggy and inefficient to be practical.</para> 29.159 + </note> 29.160 + <para id="x_513">To get going, it's best to already have a functioning copy 29.161 + of Mercurial installed.</para> 29.162 + <note> 29.163 + <para id="x_514"> If you follow the instructions below, you'll be 29.164 + <emphasis>replacing</emphasis> and overwriting any existing 29.165 + installation of Mercurial that you might already have, using 29.166 + the latest <quote>bleeding edge</quote> Mercurial code. Don't 29.167 + say you weren't warned!</para> 29.168 + </note> 29.169 + <orderedlist> 29.170 + <listitem><para id="x_515">Clone the Python <literal>inotify</literal> 29.171 + binding repository. Build and install it.</para> 29.172 + <programlisting>hg clone http://hg.kublai.com/python/inotify 29.173 +cd inotify 29.174 +python setup.py build --force 29.175 +sudo python setup.py install --skip-build</programlisting> 29.176 + </listitem> 29.177 + <listitem><para id="x_516">Clone the <filename 29.178 + class="directory">crew</filename> Mercurial repository. 29.179 + Clone the <literal role="hg-ext">inotify</literal> patch 29.180 + repository so that Mercurial Queues will be able to apply 29.181 + patches to your cope of the <filename 29.182 + class="directory">crew</filename> repository.</para> 29.183 + <programlisting>hg clone http://hg.intevation.org/mercurial/crew 29.184 +hg clone crew inotify 29.185 +hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting> 29.186 + </listitem> 29.187 + <listitem><para id="x_517">Make sure that you have the Mercurial Queues 29.188 + extension, <literal role="hg-ext">mq</literal>, enabled. If 29.189 + you've never used MQ, read <xref 29.190 + linkend="sec:mq:start"/> to get started 29.191 + quickly.</para> 29.192 + </listitem> 29.193 + <listitem><para id="x_518">Go into the <filename 29.194 + class="directory">inotify</filename> repo, and apply all 29.195 + of the <literal role="hg-ext">inotify</literal> patches 29.196 + using the <option role="hg-ext-mq-cmd-qpush-opt">hg 29.197 + -a</option> option to the <command 29.198 + role="hg-ext-mq">qpush</command> command.</para> 29.199 + <programlisting>cd inotify 29.200 +hg qpush -a</programlisting> 29.201 + </listitem> 29.202 + <listitem><para id="x_519"> If you get an error message from <command 29.203 + role="hg-ext-mq">qpush</command>, you should not continue. 29.204 + Instead, ask for help.</para> 29.205 + </listitem> 29.206 + <listitem><para id="x_51a">Build and install the patched version of 29.207 + Mercurial.</para> 29.208 + <programlisting>python setup.py build --force 29.209 +sudo python setup.py install --skip-build</programlisting> 29.210 + </listitem> 29.211 + </orderedlist> 29.212 + <para id="x_51b">Once you've build a suitably patched version of Mercurial, 29.213 + all you need to do to enable the <literal 29.214 + role="hg-ext">inotify</literal> extension is add an entry to 29.215 + your <filename role="special">~/.hgrc</filename>.</para> 29.216 + <programlisting>[extensions] inotify =</programlisting> 29.217 + <para id="x_51c">When the <literal role="hg-ext">inotify</literal> extension 29.218 + is enabled, Mercurial will automatically and transparently start 29.219 + the status daemon the first time you run a command that needs 29.220 + status in a repository. It runs one status daemon per 29.221 + repository.</para> 29.222 + 29.223 + <para id="x_51d">The status daemon is started silently, and runs in the 29.224 + background. If you look at a list of running processes after 29.225 + you've enabled the <literal role="hg-ext">inotify</literal> 29.226 + extension and run a few commands in different repositories, 29.227 + you'll thus see a few <literal>hg</literal> processes sitting 29.228 + around, waiting for updates from the kernel and queries from 29.229 + Mercurial.</para> 29.230 + 29.231 + <para id="x_51e">The first time you run a Mercurial command in a repository 29.232 + when you have the <literal role="hg-ext">inotify</literal> 29.233 + extension enabled, it will run with about the same performance 29.234 + as a normal Mercurial command. This is because the status 29.235 + daemon needs to perform a normal status scan so that it has a 29.236 + baseline against which to apply later updates from the kernel. 29.237 + However, <emphasis>every</emphasis> subsequent command that does 29.238 + any kind of status check should be noticeably faster on 29.239 + repositories of even fairly modest size. Better yet, the bigger 29.240 + your repository is, the greater a performance advantage you'll 29.241 + see. The <literal role="hg-ext">inotify</literal> daemon makes 29.242 + status operations almost instantaneous on repositories of all 29.243 + sizes!</para> 29.244 + 29.245 + <para id="x_51f">If you like, you can manually start a status daemon using 29.246 + the <command role="hg-ext-inotify">inserve</command> command. 29.247 + This gives you slightly finer control over how the daemon ought 29.248 + to run. This command will of course only be available when the 29.249 + <literal role="hg-ext">inotify</literal> extension is 29.250 + enabled.</para> 29.251 + 29.252 + <para id="x_520">When you're using the <literal 29.253 + role="hg-ext">inotify</literal> extension, you should notice 29.254 + <emphasis>no difference at all</emphasis> in Mercurial's 29.255 + behavior, with the sole exception of status-related commands 29.256 + running a whole lot faster than they used to. You should 29.257 + specifically expect that commands will not print different 29.258 + output; neither should they give different results. If either of 29.259 + these situations occurs, please report a bug.</para> 29.260 + 29.261 + </sect1> 29.262 + <sect1 id="sec:hgext:extdiff"> 29.263 + <title>Flexible diff support with the <literal 29.264 + role="hg-ext">extdiff</literal> extension</title> 29.265 + 29.266 + <para id="x_521">Mercurial's built-in <command role="hg-cmd">hg 29.267 + diff</command> command outputs plaintext unified diffs.</para> 29.268 + 29.269 + &interaction.extdiff.diff; 29.270 + 29.271 + <para id="x_522">If you would like to use an external tool to display 29.272 + modifications, you'll want to use the <literal 29.273 + role="hg-ext">extdiff</literal> extension. This will let you 29.274 + use, for example, a graphical diff tool.</para> 29.275 + 29.276 + <para id="x_523">The <literal role="hg-ext">extdiff</literal> extension is 29.277 + bundled with Mercurial, so it's easy to set up. In the <literal 29.278 + role="rc-extensions">extensions</literal> section of your 29.279 + <filename role="special">~/.hgrc</filename>, simply add a 29.280 + one-line entry to enable the extension.</para> 29.281 + <programlisting>[extensions] 29.282 +extdiff =</programlisting> 29.283 + <para id="x_524">This introduces a command named <command 29.284 + role="hg-ext-extdiff">extdiff</command>, which by default uses 29.285 + your system's <command>diff</command> command to generate a 29.286 + unified diff in the same form as the built-in <command 29.287 + role="hg-cmd">hg diff</command> command.</para> 29.288 + 29.289 + &interaction.extdiff.extdiff; 29.290 + 29.291 + <para id="x_525">The result won't be exactly the same as with the built-in 29.292 + <command role="hg-cmd">hg diff</command> variations, because the 29.293 + output of <command>diff</command> varies from one system to 29.294 + another, even when passed the same options.</para> 29.295 + 29.296 + <para id="x_526">As the <quote><literal>making snapshot</literal></quote> 29.297 + lines of output above imply, the <command 29.298 + role="hg-ext-extdiff">extdiff</command> command works by 29.299 + creating two snapshots of your source tree. The first snapshot 29.300 + is of the source revision; the second, of the target revision or 29.301 + working directory. The <command 29.302 + role="hg-ext-extdiff">extdiff</command> command generates 29.303 + these snapshots in a temporary directory, passes the name of 29.304 + each directory to an external diff viewer, then deletes the 29.305 + temporary directory. For efficiency, it only snapshots the 29.306 + directories and files that have changed between the two 29.307 + revisions.</para> 29.308 + 29.309 + <para id="x_527">Snapshot directory names have the same base name as your 29.310 + repository. If your repository path is <filename 29.311 + class="directory">/quux/bar/foo</filename>, then <filename 29.312 + class="directory">foo</filename> will be the name of each 29.313 + snapshot directory. Each snapshot directory name has its 29.314 + changeset ID appended, if appropriate. If a snapshot is of 29.315 + revision <literal>a631aca1083f</literal>, the directory will be 29.316 + named <filename class="directory">foo.a631aca1083f</filename>. 29.317 + A snapshot of the working directory won't have a changeset ID 29.318 + appended, so it would just be <filename 29.319 + class="directory">foo</filename> in this example. To see what 29.320 + this looks like in practice, look again at the <command 29.321 + role="hg-ext-extdiff">extdiff</command> example above. Notice 29.322 + that the diff has the snapshot directory names embedded in its 29.323 + header.</para> 29.324 + 29.325 + <para id="x_528">The <command role="hg-ext-extdiff">extdiff</command> command 29.326 + accepts two important options. The <option 29.327 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option 29.328 + lets you choose a program to view differences with, instead of 29.329 + <command>diff</command>. With the <option 29.330 + role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option, 29.331 + you can change the options that <command 29.332 + role="hg-ext-extdiff">extdiff</command> passes to the program 29.333 + (by default, these options are 29.334 + <quote><literal>-Npru</literal></quote>, which only make sense 29.335 + if you're running <command>diff</command>). In other respects, 29.336 + the <command role="hg-ext-extdiff">extdiff</command> command 29.337 + acts similarly to the built-in <command role="hg-cmd">hg 29.338 + diff</command> command: you use the same option names, syntax, 29.339 + and arguments to specify the revisions you want, the files you 29.340 + want, and so on.</para> 29.341 + 29.342 + <para id="x_529">As an example, here's how to run the normal system 29.343 + <command>diff</command> command, getting it to generate context 29.344 + diffs (using the <option role="cmd-opt-diff">-c</option> option) 29.345 + instead of unified diffs, and five lines of context instead of 29.346 + the default three (passing <literal>5</literal> as the argument 29.347 + to the <option role="cmd-opt-diff">-C</option> option).</para> 29.348 + 29.349 + &interaction.extdiff.extdiff-ctx; 29.350 + 29.351 + <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to 29.352 + launch the <command>kdiff3</command> viewer.</para> 29.353 + <programlisting>hg extdiff -p kdiff3 -o</programlisting> 29.354 + 29.355 + <para id="x_52b">If your diff viewing command can't deal with directories, 29.356 + you can easily work around this with a little scripting. For an 29.357 + example of such scripting in action with the <literal 29.358 + role="hg-ext">mq</literal> extension and the 29.359 + <command>interdiff</command> command, see <xref 29.360 + linkend="mq-collab:tips:interdiff"/>.</para> 29.361 + 29.362 + <sect2> 29.363 + <title>Defining command aliases</title> 29.364 + 29.365 + <para id="x_52c">It can be cumbersome to remember the options to both the 29.366 + <command role="hg-ext-extdiff">extdiff</command> command and 29.367 + the diff viewer you want to use, so the <literal 29.368 + role="hg-ext">extdiff</literal> extension lets you define 29.369 + <emphasis>new</emphasis> commands that will invoke your diff 29.370 + viewer with exactly the right options.</para> 29.371 + 29.372 + <para id="x_52d">All you need to do is edit your <filename 29.373 + role="special">~/.hgrc</filename>, and add a section named 29.374 + <literal role="rc-extdiff">extdiff</literal>. Inside this 29.375 + section, you can define multiple commands. Here's how to add 29.376 + a <literal>kdiff3</literal> command. Once you've defined 29.377 + this, you can type <quote><literal>hg kdiff3</literal></quote> 29.378 + and the <literal role="hg-ext">extdiff</literal> extension 29.379 + will run <command>kdiff3</command> for you.</para> 29.380 + <programlisting>[extdiff] 29.381 +cmd.kdiff3 =</programlisting> 29.382 + <para id="x_52e">If you leave the right hand side of the definition empty, 29.383 + as above, the <literal role="hg-ext">extdiff</literal> 29.384 + extension uses the name of the command you defined as the name 29.385 + of the external program to run. But these names don't have to 29.386 + be the same. Here, we define a command named 29.387 + <quote><literal>hg wibble</literal></quote>, which runs 29.388 + <command>kdiff3</command>.</para> 29.389 + <programlisting>[extdiff] 29.390 + cmd.wibble = kdiff3</programlisting> 29.391 + 29.392 + <para id="x_52f">You can also specify the default options that you want to 29.393 + invoke your diff viewing program with. The prefix to use is 29.394 + <quote><literal>opts.</literal></quote>, followed by the name 29.395 + of the command to which the options apply. This example 29.396 + defines a <quote><literal>hg vimdiff</literal></quote> command 29.397 + that runs the <command>vim</command> editor's 29.398 + <literal>DirDiff</literal> extension.</para> 29.399 + <programlisting>[extdiff] 29.400 + cmd.vimdiff = vim 29.401 +opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting> 29.402 + 29.403 + </sect2> 29.404 + </sect1> 29.405 + <sect1 id="sec:hgext:transplant"> 29.406 + <title>Cherrypicking changes with the <literal 29.407 + role="hg-ext">transplant</literal> extension</title> 29.408 + 29.409 + <para id="x_530">Need to have a long chat with Brendan about this.</para> 29.410 + 29.411 + </sect1> 29.412 + <sect1 id="sec:hgext:patchbomb"> 29.413 + <title>Send changes via email with the <literal 29.414 + role="hg-ext">patchbomb</literal> extension</title> 29.415 + 29.416 + <para id="x_531">Many projects have a culture of <quote>change 29.417 + review</quote>, in which people send their modifications to a 29.418 + mailing list for others to read and comment on before they 29.419 + commit the final version to a shared repository. Some projects 29.420 + have people who act as gatekeepers; they apply changes from 29.421 + other people to a repository to which those others don't have 29.422 + access.</para> 29.423 + 29.424 + <para id="x_532">Mercurial makes it easy to send changes over email for 29.425 + review or application, via its <literal 29.426 + role="hg-ext">patchbomb</literal> extension. The extension is 29.427 + so named because changes are formatted as patches, and it's usual 29.428 + to send one changeset per email message. Sending a long series 29.429 + of changes by email is thus much like <quote>bombing</quote> the 29.430 + recipient's inbox, hence <quote>patchbomb</quote>.</para> 29.431 + 29.432 + <para id="x_533">As usual, the basic configuration of the <literal 29.433 + role="hg-ext">patchbomb</literal> extension takes just one or 29.434 + two lines in your <filename role="special"> 29.435 + /.hgrc</filename>.</para> 29.436 + <programlisting>[extensions] 29.437 +patchbomb =</programlisting> 29.438 + <para id="x_534">Once you've enabled the extension, you will have a new 29.439 + command available, named <command 29.440 + role="hg-ext-patchbomb">email</command>.</para> 29.441 + 29.442 + <para id="x_535">The safest and best way to invoke the <command 29.443 + role="hg-ext-patchbomb">email</command> command is to 29.444 + <emphasis>always</emphasis> run it first with the <option 29.445 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option. 29.446 + This will show you what the command <emphasis>would</emphasis> 29.447 + send, without actually sending anything. Once you've had a 29.448 + quick glance over the changes and verified that you are sending 29.449 + the right ones, you can rerun the same command, with the <option 29.450 + role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option 29.451 + removed.</para> 29.452 + 29.453 + <para id="x_536">The <command role="hg-ext-patchbomb">email</command> command 29.454 + accepts the same kind of revision syntax as every other 29.455 + Mercurial command. For example, this command will send every 29.456 + revision between 7 and <literal>tip</literal>, inclusive.</para> 29.457 + <programlisting>hg email -n 7:tip</programlisting> 29.458 + <para id="x_537">You can also specify a <emphasis>repository</emphasis> to 29.459 + compare with. If you provide a repository but no revisions, the 29.460 + <command role="hg-ext-patchbomb">email</command> command will 29.461 + send all revisions in the local repository that are not present 29.462 + in the remote repository. If you additionally specify revisions 29.463 + or a branch name (the latter using the <option 29.464 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option), 29.465 + this will constrain the revisions sent.</para> 29.466 + 29.467 + <para id="x_538">It's perfectly safe to run the <command 29.468 + role="hg-ext-patchbomb">email</command> command without the 29.469 + names of the people you want to send to: if you do this, it will 29.470 + just prompt you for those values interactively. (If you're 29.471 + using a Linux or Unix-like system, you should have enhanced 29.472 + <literal>readline</literal>-style editing capabilities when 29.473 + entering those headers, too, which is useful.)</para> 29.474 + 29.475 + <para id="x_539">When you are sending just one revision, the <command 29.476 + role="hg-ext-patchbomb">email</command> command will by 29.477 + default use the first line of the changeset description as the 29.478 + subject of the single email message it sends.</para> 29.479 + 29.480 + <para id="x_53a">If you send multiple revisions, the <command 29.481 + role="hg-ext-patchbomb">email</command> command will usually 29.482 + send one message per changeset. It will preface the series with 29.483 + an introductory message, in which you should describe the 29.484 + purpose of the series of changes you're sending.</para> 29.485 + 29.486 + <sect2> 29.487 + <title>Changing the behavior of patchbombs</title> 29.488 + 29.489 + <para id="x_53b">Not every project has exactly the same conventions for 29.490 + sending changes in email; the <literal 29.491 + role="hg-ext">patchbomb</literal> extension tries to 29.492 + accommodate a number of variations through command line 29.493 + options.</para> 29.494 + <itemizedlist> 29.495 + <listitem><para id="x_53c">You can write a subject for the introductory 29.496 + message on the command line using the <option 29.497 + role="hg-ext-patchbomb-cmd-email-opt">hg -s</option> 29.498 + option. This takes one argument, the text of the subject 29.499 + to use.</para> 29.500 + </listitem> 29.501 + <listitem><para id="x_53d">To change the email address from which the 29.502 + messages originate, use the <option 29.503 + role="hg-ext-patchbomb-cmd-email-opt">hg -f</option> 29.504 + option. This takes one argument, the email address to 29.505 + use.</para> 29.506 + </listitem> 29.507 + <listitem><para id="x_53e">The default behavior is to send unified diffs 29.508 + (see <xref linkend="sec:mq:patch"/> for a 29.509 + description of the 29.510 + format), one per message. You can send a binary bundle 29.511 + instead with the <option 29.512 + role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> 29.513 + option.</para> 29.514 + </listitem> 29.515 + <listitem><para id="x_53f">Unified diffs are normally prefaced with a 29.516 + metadata header. You can omit this, and send unadorned 29.517 + diffs, with the <option 29.518 + role="hg-ext-patchbomb-cmd-email-opt">hg 29.519 + --plain</option> option.</para> 29.520 + </listitem> 29.521 + <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>, 29.522 + in the same body part as the description of a patch. This 29.523 + makes it easiest for the largest number of readers to 29.524 + quote and respond to parts of a diff, as some mail clients 29.525 + will only quote the first MIME body part in a message. If 29.526 + you'd prefer to send the description and the diff in 29.527 + separate body parts, use the <option 29.528 + role="hg-ext-patchbomb-cmd-email-opt">hg -a</option> 29.529 + option.</para> 29.530 + </listitem> 29.531 + <listitem><para id="x_541">Instead of sending mail messages, you can 29.532 + write them to an <literal>mbox</literal>-format mail 29.533 + folder using the <option 29.534 + role="hg-ext-patchbomb-cmd-email-opt">hg -m</option> 29.535 + option. That option takes one argument, the name of the 29.536 + file to write to.</para> 29.537 + </listitem> 29.538 + <listitem><para id="x_542">If you would like to add a 29.539 + <command>diffstat</command>-format summary to each patch, 29.540 + and one to the introductory message, use the <option 29.541 + role="hg-ext-patchbomb-cmd-email-opt">hg -d</option> 29.542 + option. The <command>diffstat</command> command displays 29.543 + a table containing the name of each file patched, the 29.544 + number of lines affected, and a histogram showing how much 29.545 + each file is modified. This gives readers a qualitative 29.546 + glance at how complex a patch is.</para> 29.547 + </listitem></itemizedlist> 29.548 + 29.549 + </sect2> 29.550 + </sect1> 29.551 +</chapter> 29.552 + 29.553 +<!-- 29.554 +local variables: 29.555 +sgml-parent-document: ("00book.xml" "book" "chapter") 29.556 +end: 29.557 +-->