hgbook
changeset 678:743dc55775fe
Merged upstream
| author | Raphael Borun Das Gupta <hg@raphael.dasgupta.ch> |
|---|---|
| date | Sat Apr 18 17:45:54 2009 +0200 (2009-04-18) |
| parents | 83540574ee49 29f0f79cf614 |
| children | 06458701453c |
| files | en/ch05-collab.xml |
line diff
1.1 --- a/en/ch01-tour-basic.xml Sat Apr 18 17:38:07 2009 +0200 1.2 +++ b/en/ch01-tour-basic.xml Sat Apr 18 17:45:54 2009 +0200 1.3 @@ -131,7 +131,7 @@ 1.4 1.5 &interaction.tour.clone; 1.6 1.7 - <para>One advantage of using <command role="hg-cmd">hg 1.8 + <para id="x_67c">One advantage of using <command role="hg-cmd">hg 1.9 clone</command> is that, as we can see above, it lets us clone 1.10 repositories over the network. Another is that it remembers 1.11 where we cloned from, which we'll find useful soon when we 1.12 @@ -233,7 +233,7 @@ 1.13 the text message that the creator of the changeset entered 1.14 to describe the changeset.</para></listitem> 1.15 <listitem> 1.16 - <para>Some changesets, such as the first in the list above, 1.17 + <para id="x_67d">Some changesets, such as the first in the list above, 1.18 have a <literal>tag</literal> field. A tag is another way 1.19 to identify a changeset, by giving it an easy-to-remember 1.20 name. (The tag named <literal>tip</literal> is special: it 1.21 @@ -364,7 +364,7 @@ 1.22 1.23 &interaction.tour.log-vp; 1.24 1.25 - <para>The <option role="hg-opt-log">-p</option> option is 1.26 + <para id="x_67e">The <option role="hg-opt-log">-p</option> option is 1.27 tremendously useful, so it's well worth remembering.</para> 1.28 1.29 </sect2> 1.30 @@ -410,7 +410,7 @@ 1.31 role="hg-opt-log">--rev</option> arguments.</para> 1.32 </listitem> 1.33 <listitem> 1.34 - <para>If you are using short options, you can save typing by 1.35 + <para id="x_67f">If you are using short options, you can save typing by 1.36 running them together. For example, the command <command 1.37 role="hg-cmd">hg log -v -p -r 2</command> can be written 1.38 as <command role="hg-cmd">hg log -vpr2</command>.</para> 1.39 @@ -430,7 +430,7 @@ 1.40 <note> 1.41 <title>Option naming consistency</title> 1.42 1.43 - <para>Almost always, Mercurial commands use consistent option 1.44 + <para id="x_680">Almost always, Mercurial commands use consistent option 1.45 names to refer to the same concepts. For instance, if a 1.46 command deals with changesets, you'll always identify them 1.47 with <option role="hg-opt-log">--rev</option> or <option 1.48 @@ -454,7 +454,7 @@ 1.49 locally, we can just clone that instead. This is much faster 1.50 than cloning over the network, and cloning a local repository 1.51 uses less disk space in most cases, too<footnote> 1.52 - <para>The saving of space arises when source and destination 1.53 + <para id="x_681">The saving of space arises when source and destination 1.54 repositories are on the same filesystem, in which case 1.55 Mercurial will use hardlinks to do copy-on-write sharing of 1.56 its internal metadata. If that explanation meant nothing to 1.57 @@ -479,7 +479,7 @@ 1.58 1.59 &interaction.tour.cat1; 1.60 1.61 - <para>Let's edit this file so that it prints a second line of 1.62 + <para id="x_682">Let's edit this file so that it prints a second line of 1.63 output.</para> 1.64 1.65 &interaction.tour.cat2; 1.66 @@ -516,7 +516,7 @@ 1.67 <tip> 1.68 <title>Understanding patches</title> 1.69 1.70 - <para>Remember to take a look at <xref 1.71 + <para id="x_683">Remember to take a look at <xref 1.72 linkend="sec:mq:patch"/> if you don't know how to read 1.73 output above.</para> 1.74 </tip> 1.75 @@ -726,7 +726,7 @@ 1.76 repository as the <emphasis>tip revision</emphasis>, or simply 1.77 the <emphasis>tip</emphasis>.</para> 1.78 1.79 - <para>By the way, the <command role="hg-cmd">hg tip</command> 1.80 + <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command> 1.81 command accepts many of the same options as <command 1.82 role="hg-cmd">hg log</command>, so <option 1.83 role="hg-opt-global">-v</option> above indicates <quote>be
2.1 --- a/en/ch02-tour-merge.xml Sat Apr 18 17:38:07 2009 +0200 2.2 +++ b/en/ch02-tour-merge.xml Sat Apr 18 17:45:54 2009 +0200 2.3 @@ -164,7 +164,7 @@ 2.4 </mediaobject> 2.5 </figure> 2.6 2.7 - <para>We sometimes talk about a merge having 2.8 + <para id="x_69c">We sometimes talk about a merge having 2.9 <emphasis>sides</emphasis>: the left side is the first parent 2.10 in the output of <command role="hg-cmd">hg parents</command>, 2.11 and the right side is the second. If the working directory
3.1 --- a/en/ch03-concepts.xml Sat Apr 18 17:38:07 2009 +0200 3.2 +++ b/en/ch03-concepts.xml Sat Apr 18 17:45:54 2009 +0200 3.3 @@ -524,13 +524,13 @@ 3.4 <sect2> 3.5 <title>Merging and renames</title> 3.6 3.7 - <para>A surprising number of revision control systems pay little 3.8 + <para id="x_69a">A surprising number of revision control systems pay little 3.9 or no attention to a file's <emphasis>name</emphasis> over 3.10 time. For instance, it used to be common that if a file got 3.11 renamed on one side of a merge, the changes from the other 3.12 side would be silently dropped.</para> 3.13 3.14 - <para>Mercurial records metadata when you tell it to perform a 3.15 + <para id="x_69b">Mercurial records metadata when you tell it to perform a 3.16 rename or copy. It uses this metadata during a merge to do the 3.17 right thing in the case of a merge. For instance, if I rename 3.18 a file, and you edit it without renaming it, when we merge our
4.1 --- a/en/ch04-daily.xml Sat Apr 18 17:38:07 2009 +0200 4.2 +++ b/en/ch04-daily.xml Sat Apr 18 17:45:54 2009 +0200 4.3 @@ -357,7 +357,7 @@ 4.4 <emphasis>destination</emphasis>, and all others are 4.5 <emphasis>sources</emphasis>.</para> 4.6 4.7 - <para>If you pass <command role="hg-cmd">hg copy</command> a 4.8 + <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a 4.9 single file as the source, and the destination does not exist, 4.10 it creates a new file with that name.</para> 4.11 4.12 @@ -430,7 +430,7 @@ 4.13 similar to the <command role="hg-cmd">hg copy</command> 4.14 command.</para> 4.15 4.16 - <para>If you're familiar with the Unix command line, you'll be 4.17 + <para id="x_686">If you're familiar with the Unix command line, you'll be 4.18 glad to know that <command role="hg-cmd">hg rename</command> 4.19 command can be invoked as <command role="hg-cmd">hg 4.20 mv</command>.</para> 4.21 @@ -550,37 +550,37 @@ 4.22 <sect1> 4.23 <title>Dealing with tricky merges</title> 4.24 4.25 - <para>In a complicated or large project, it's not unusual for a 4.26 + <para id="x_687">In a complicated or large project, it's not unusual for a 4.27 merge of two changesets to result in some headaches. Suppose 4.28 there's a big source file that's been extensively edited by each 4.29 side of a merge: this is almost inevitably going to result in 4.30 conflicts, some of which can take a few tries to sort 4.31 out.</para> 4.32 4.33 - <para>Let's develop a simple case of this and see how to deal with 4.34 + <para id="x_688">Let's develop a simple case of this and see how to deal with 4.35 it. We'll start off with a repository containing one file, and 4.36 clone it twice.</para> 4.37 4.38 &interaction.ch04-resolve.init; 4.39 4.40 - <para>In one clone, we'll modify the file in one way.</para> 4.41 + <para id="x_689">In one clone, we'll modify the file in one way.</para> 4.42 4.43 &interaction.ch04-resolve.left; 4.44 4.45 - <para>In another, we'll modify the file differently.</para> 4.46 + <para id="x_68a">In another, we'll modify the file differently.</para> 4.47 4.48 &interaction.ch04-resolve.right; 4.49 4.50 - <para>Next, we'll pull each set of changes into our original 4.51 + <para id="x_68b">Next, we'll pull each set of changes into our original 4.52 repo.</para> 4.53 4.54 &interaction.ch04-resolve.pull; 4.55 4.56 - <para>We expect our repository to now contain two heads.</para> 4.57 + <para id="x_68c">We expect our repository to now contain two heads.</para> 4.58 4.59 &interaction.ch04-resolve.heads; 4.60 4.61 - <para>Normally, if we run <command role="hg-cmd">hg 4.62 + <para id="x_68d">Normally, if we run <command role="hg-cmd">hg 4.63 merge</command> at this point, it will drop us into a GUI that 4.64 will let us manually resolve the conflicting edits to 4.65 <filename>myfile.txt</filename>. However, to simplify things 4.66 @@ -589,24 +589,24 @@ 4.67 4.68 &interaction.ch04-resolve.export; 4.69 4.70 - <para>We've told Mercurial's merge machinery to run the command 4.71 + <para id="x_68e">We've told Mercurial's merge machinery to run the command 4.72 <command>false</command> (which, as we desire, fails 4.73 immediately) if it detects a merge that it can't sort out 4.74 automatically.</para> 4.75 4.76 - <para>If we now fire up <command role="hg-cmd">hg 4.77 + <para id="x_68f">If we now fire up <command role="hg-cmd">hg 4.78 merge</command>, it should grind to a halt and report a 4.79 failure.</para> 4.80 4.81 &interaction.ch04-resolve.merge; 4.82 4.83 - <para>Even if we don't notice that the merge failed, Mercurial 4.84 + <para id="x_690">Even if we don't notice that the merge failed, Mercurial 4.85 will prevent us from accidentally committing the result of a 4.86 failed merge.</para> 4.87 4.88 &interaction.ch04-resolve.cifail; 4.89 4.90 - <para>When <command role="hg-cmd">hg commit</command> fails in 4.91 + <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in 4.92 this case, it suggests that we use the unfamiliar <command 4.93 role="hg-cmd">hg resolve</command> command. As usual, 4.94 <command role="hg-cmd">hg help resolve</command> will print a 4.95 @@ -615,35 +615,35 @@ 4.96 <sect2> 4.97 <title>File resolution states</title> 4.98 4.99 - <para>When a merge occurs, most files will usually remain 4.100 + <para id="x_692">When a merge occurs, most files will usually remain 4.101 unmodified. For each file where Mercurial has to do 4.102 something, it tracks the state of the file.</para> 4.103 4.104 <itemizedlist> 4.105 <listitem> 4.106 - <para>A <emphasis>resolved</emphasis> file has been 4.107 + <para id="x_693">A <emphasis>resolved</emphasis> file has been 4.108 successfully merged, either automatically by Mercurial or 4.109 manually with human intervention.</para> 4.110 </listitem> 4.111 <listitem> 4.112 - <para>An <emphasis>unresolved</emphasis> file was not merged 4.113 + <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged 4.114 successfully, and needs more attention.</para> 4.115 </listitem> 4.116 </itemizedlist> 4.117 4.118 - <para>If Mercurial sees <emphasis>any</emphasis> file in the 4.119 + <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the 4.120 unresolved state after a merge, it considers the merge to have 4.121 failed. Fortunately, we do not need to restart the entire 4.122 merge from scratch.</para> 4.123 4.124 - <para>The <option role="hg-opt-resolve">--list</option> or 4.125 + <para id="x_696">The <option role="hg-opt-resolve">--list</option> or 4.126 <option role="hg-opt-resolve">-l</option> option to <command 4.127 role="hg-cmd">hg resolve</command> prints out the state of 4.128 each merged file.</para> 4.129 4.130 &interaction.ch04-resolve.list; 4.131 4.132 - <para>In the output from <command role="hg-cmd">hg 4.133 + <para id="x_697">In the output from <command role="hg-cmd">hg 4.134 resolve</command>, a resolved file is marked with 4.135 <literal>R</literal>, while an unresolved file is marked with 4.136 <literal>U</literal>. If any files are listed with 4.137 @@ -654,7 +654,7 @@ 4.138 <sect2> 4.139 <title>Resolving a file merge</title> 4.140 4.141 - <para>We have several options to move a file from the unresolved 4.142 + <para id="x_698">We have several options to move a file from the unresolved 4.143 into the resolved state. By far the most common is to rerun 4.144 <command role="hg-cmd">hg resolve</command>. If we pass the 4.145 names of individual files or directories, it will retry the 4.146 @@ -664,7 +664,7 @@ 4.147 will retry the merges of <emphasis>all</emphasis> unresolved 4.148 files.</para> 4.149 4.150 - <para>Mercurial also lets us modify the resolution state of a 4.151 + <para id="x_699">Mercurial also lets us modify the resolution state of a 4.152 file directly. We can manually mark a file as resolved using 4.153 the <option role="hg-opt-resolve">--mark</option> option, or 4.154 as unresolved using the <option
5.1 --- a/en/ch05-collab.xml Sat Apr 18 17:38:07 2009 +0200 5.2 +++ b/en/ch05-collab.xml Sat Apr 18 17:45:54 2009 +0200 5.3 @@ -19,10 +19,12 @@ 5.4 <para id="x_44c">For interactive use, the web interface lets you browse a 5.5 single repository or a collection of repositories. You can view 5.6 the history of a repository, examine each change (comments and 5.7 - diffs), and view the contents of each directory and file.</para> 5.8 - 5.9 - <para id="x_44d">Also for human consumption, the web interface provides an 5.10 - RSS feed of the changes in a repository. This lets you 5.11 + diffs), and view the contents of each directory and file. You 5.12 + can even get a view of history that gives a graphical view of 5.13 + the relationships between individual changes and merges.</para> 5.14 + 5.15 + <para id="x_44d">Also for human consumption, the web interface provides 5.16 + Atom and RSS feeds of the changes in a repository. This lets you 5.17 <quote>subscribe</quote> to a repository using your favorite 5.18 feed reader, and be automatically notified of activity in that 5.19 repository as soon as it happens. I find this capability much 5.20 @@ -40,22 +42,40 @@ 5.21 <para id="x_44f">The easiest way to get started with the web interface is to 5.22 use your web browser to visit an existing repository, such as 5.23 the master Mercurial repository at <ulink 5.24 - url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para> 5.25 + url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para> 5.26 5.27 <para id="x_450">If you're interested in providing a web interface 5.28 - to your own repositories, Mercurial provides two ways to do 5.29 - this. The first is using the <command role="hg-cmd">hg 5.30 + to your own repositories, there are several good ways to do 5.31 + this.</para> 5.32 + 5.33 + <para id="x_69d">The easiest and fastest way to get started in an informal 5.34 + environment is to use the <command role="hg-cmd">hg 5.35 serve</command> command, which is best suited to short-term 5.36 <quote>lightweight</quote> serving. See <xref 5.37 linkend="sec:collab:serve"/> below for details of how to use 5.38 - this command. If you have a long-lived repository that you'd 5.39 - like to make permanently available, Mercurial has built-in 5.40 - support for the CGI (Common Gateway Interface) standard, which 5.41 - all common web servers support. See <xref 5.42 - linkend="sec:collab:cgi"/> for details of CGI 5.43 + this command.</para> 5.44 + 5.45 + <para id="x_69e">For longer-lived repositories that you'd like to have 5.46 + permanently available, there are several public hosting services 5.47 + available.</para> 5.48 + 5.49 + <itemizedlist> 5.50 + <listitem> 5.51 + <para id="x_69f">Bitbucket, at <ulink 5.52 + url="http://bitbucket.org/">http://bitbucket.org/</ulink>, 5.53 + provides free hosting for open source projects, and paid 5.54 + hosting for commercial projects.</para> 5.55 + </listitem> 5.56 + </itemizedlist> 5.57 + 5.58 + <para id="x_6a0">If you would prefer to host your own repositories, Mercurial 5.59 + has built-in support for several popular hosting technologies, 5.60 + most notably CGI (Common Gateway Interface), and WSGI (Web 5.61 + Services Gateway Interface). See <xref 5.62 + linkend="sec:collab:cgi"/> for details of CGI and WSGI 5.63 configuration.</para> 5.64 - 5.65 </sect1> 5.66 + 5.67 <sect1> 5.68 <title>Collaboration models</title> 5.69 5.70 @@ -96,8 +116,8 @@ 5.71 could avoid this particular problem by writing a hook that 5.72 prevents changes from being merged from an inappropriate 5.73 branch.</para> 5.74 - 5.75 - </sect2> 5.76 + </sect2> 5.77 + 5.78 <sect2> 5.79 <title>Informal anarchy</title> 5.80 5.81 @@ -115,7 +135,7 @@ 5.82 place) and spend several days more or less locked in there, 5.83 hacking intensely on a handful of projects.</para> 5.84 5.85 - <para id="x_457">A sprint is the perfect place to use the 5.86 + <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the 5.87 <command role="hg-cmd">hg serve</command> command, since 5.88 <command role="hg-cmd">hg serve</command> does not require any 5.89 fancy server infrastructure. You can get started with 5.90 @@ -129,14 +149,15 @@ 5.91 they can clone a branch containing a new feature and try it 5.92 out.</para> 5.93 5.94 - <para id="x_458">The charm, and the problem, with doing things in an ad hoc 5.95 - fashion like this is that only people who know about your 5.96 - changes, and where they are, can see them. Such an informal 5.97 - approach simply doesn't scale beyond a handful people, because 5.98 - each individual needs to know about $n$ different repositories 5.99 - to pull from.</para> 5.100 - 5.101 - </sect2> 5.102 + <para id="x_458">The charm, and the problem, with doing things 5.103 + in an ad hoc fashion like this is that only people who know 5.104 + about your changes, and where they are, can see them. Such an 5.105 + informal approach simply doesn't scale beyond a handful 5.106 + people, because each individual needs to know about 5.107 + <emphasis>n</emphasis> different repositories to pull 5.108 + from.</para> 5.109 + </sect2> 5.110 + 5.111 <sect2> 5.112 <title>A single central repository</title> 5.113 5.114 @@ -162,17 +183,39 @@ 5.115 lets us put off publishing the potentially unsafe change until 5.116 it has had a little testing.</para> 5.117 5.118 - <para id="x_45c">In this kind of scenario, people usually use 5.119 - the <command>ssh</command> protocol to securely push changes 5.120 - to the central repository, as documented in <xref 5.121 + <para id="x_45c">If a team is hosting its own repository in this 5.122 + kind of scenario, people will usually use the 5.123 + <command>ssh</command> protocol to securely push changes to 5.124 + the central repository, as documented in <xref 5.125 linkend="sec:collab:ssh"/>. It's also usual to publish a 5.126 - read-only copy of the repository over HTTP using CGI, as in 5.127 - <xref linkend="sec:collab:cgi"/>. Publishing 5.128 - over HTTP satisfies the needs of people who don't have push 5.129 - access, and those who want to use web browsers to browse the 5.130 - repository's history.</para> 5.131 - 5.132 - </sect2> 5.133 + read-only copy of the repository over HTTP, as in 5.134 + <xref linkend="sec:collab:cgi"/>. Publishing over HTTP 5.135 + satisfies the needs of people who don't have push access, and 5.136 + those who want to use web browsers to browse the repository's 5.137 + history.</para> 5.138 + </sect2> 5.139 + 5.140 + <sect2> 5.141 + <title>A hosted central repository</title> 5.142 + 5.143 + <para id="x_6a1">A wonderful thing about public hosting services like 5.144 + <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that 5.145 + not only do they handle the fiddly server configuration 5.146 + details, such as user accounts, authentication, and secure 5.147 + wire protocols, they provide additional infrastructure to make 5.148 + this model work well.</para> 5.149 + 5.150 + <para id="x_6a2">For instance, a well-engineered hosting service will let 5.151 + people clone their own copies of a repository with a single 5.152 + click. This lets people work in separate spaces and share 5.153 + their changes when they're ready.</para> 5.154 + 5.155 + <para id="x_6a3">In addition, a good hosting service will let people 5.156 + communicate with each other, for instance to say <quote>there 5.157 + are changes ready for you to review in this 5.158 + tree</quote>.</para> 5.159 + </sect2> 5.160 + 5.161 <sect2> 5.162 <title>Working with multiple branches</title> 5.163 5.164 @@ -196,7 +239,7 @@ 5.165 another as the need arises. Because repositories are 5.166 independent of each other, unstable changes in a development 5.167 branch will never affect a stable branch unless someone 5.168 - explicitly merges those changes in.</para> 5.169 + explicitly merges those changes into the stable branch.</para> 5.170 5.171 <para id="x_45f">Here's an example of how this can work in practice. Let's 5.172 say you have one <quote>main branch</quote> on a central 5.173 @@ -227,38 +270,41 @@ 5.174 &interaction.branching.update; 5.175 5.176 <para id="x_464">In addition, immediately after the main branch is tagged, 5.177 - someone can then clone the main branch on the server to a new 5.178 + we can then clone the main branch on the server to a new 5.179 <quote>stable</quote> branch, also on the server.</para> 5.180 5.181 &interaction.branching.clone; 5.182 5.183 - <para id="x_465">Someone who needs to make a change to the stable branch 5.184 - can then clone <emphasis>that</emphasis> repository, make 5.185 - their changes, commit, and push their changes back there.</para> 5.186 + <para id="x_465">If we need to make a change to the stable 5.187 + branch, we can then clone <emphasis>that</emphasis> 5.188 + repository, make our changes, commit, and push our changes 5.189 + back there.</para> 5.190 5.191 &interaction.branching.stable; 5.192 5.193 <para id="x_466">Because Mercurial repositories are independent, and 5.194 Mercurial doesn't move changes around automatically, the 5.195 stable and main branches are <emphasis>isolated</emphasis> 5.196 - from each other. The changes that you made on the main branch 5.197 + from each other. The changes that we made on the main branch 5.198 don't <quote>leak</quote> to the stable branch, and vice 5.199 versa.</para> 5.200 5.201 - <para id="x_467">You'll often want all of your bugfixes on the stable 5.202 + <para id="x_467">We'll often want all of our bugfixes on the stable 5.203 branch to show up on the main branch, too. Rather than 5.204 - rewrite a bugfix on the main branch, you can simply pull and 5.205 + rewrite a bugfix on the main branch, we can simply pull and 5.206 merge changes from the stable to the main branch, and 5.207 - Mercurial will bring those bugfixes in for you.</para> 5.208 - 5.209 - &interaction.branching.merge; 5.210 - 5.211 - <para id="x_468">The main branch will still contain changes that are not on 5.212 - the stable branch, but it will also contain all of the 5.213 - bugfixes from the stable branch. The stable branch remains 5.214 - unaffected by these changes.</para> 5.215 - 5.216 - </sect2> 5.217 + Mercurial will bring those bugfixes in for us.</para> 5.218 + 5.219 + &interaction.branching.merge; 5.220 + 5.221 + <para id="x_468">The main branch will still contain changes that 5.222 + are not on the stable branch, but it will also contain all of 5.223 + the bugfixes from the stable branch. The stable branch 5.224 + remains unaffected by these changes, since changes are only 5.225 + flowing from the stable to the main branch, and not the other 5.226 + way.</para> 5.227 + </sect2> 5.228 + 5.229 <sect2> 5.230 <title>Feature branches</title> 5.231 5.232 @@ -281,8 +327,8 @@ 5.233 shape, someone on that feature team pulls and merges from the 5.234 master branch into the feature branch, then pushes back up to 5.235 the master branch.</para> 5.236 - 5.237 - </sect2> 5.238 + </sect2> 5.239 + 5.240 <sect2> 5.241 <title>The release train</title> 5.242 5.243 @@ -297,8 +343,8 @@ 5.244 went out on that train release into the feature branch, and 5.245 the team continues its work on top of that release so that 5.246 their feature can make the next release.</para> 5.247 - 5.248 - </sect2> 5.249 + </sect2> 5.250 + 5.251 <sect2> 5.252 <title>The Linux kernel model</title> 5.253 5.254 @@ -372,8 +418,8 @@ 5.255 it appropriate; and the pace of development is astounding. 5.256 And yet Linux is a highly successful, well-regarded piece of 5.257 software.</para> 5.258 - 5.259 - </sect2> 5.260 + </sect2> 5.261 + 5.262 <sect2> 5.263 <title>Pull-only versus shared-push collaboration</title> 5.264 5.265 @@ -391,12 +437,11 @@ 5.266 you'll have to roll your own approach on top (such as applying 5.267 a patch by hand).</para> 5.268 5.269 - <para id="x_478">A good distributed revision control tool, such as 5.270 - Mercurial, will support both models. You and your 5.271 - collaborators can then structure how you work together based 5.272 - on your own needs and preferences, not on what contortions 5.273 - your tools force you into.</para> 5.274 - 5.275 + <para id="x_478">A good distributed revision control tool will 5.276 + support both models. You and your collaborators can then 5.277 + structure how you work together based on your own needs and 5.278 + preferences, not on what contortions your tools force you 5.279 + into.</para> 5.280 </sect2> 5.281 <sect2> 5.282 <title>Where collaboration meets branch management</title> 5.283 @@ -409,16 +454,16 @@ 5.284 Even though this subject is intimately related to how your 5.285 team collaborates, it's dense enough to merit treatment of its 5.286 own, in <xref linkend="chap:branch"/>.</para> 5.287 - 5.288 </sect2> 5.289 </sect1> 5.290 + 5.291 <sect1> 5.292 <title>The technical side of sharing</title> 5.293 5.294 <para id="x_47a">The remainder of this chapter is devoted to the question of 5.295 - serving data to your collaborators.</para> 5.296 - 5.297 + sharing changes with your collaborators.</para> 5.298 </sect1> 5.299 + 5.300 <sect1 id="sec:collab:serve"> 5.301 <title>Informal sharing with <command role="hg-cmd">hg 5.302 serve</command></title> 5.303 @@ -495,9 +540,9 @@ 5.304 find out what URL you should send to your collaborators, start 5.305 it with the <option role="hg-opt-global">-v</option> 5.306 option.</para> 5.307 - 5.308 </sect2> 5.309 </sect1> 5.310 + 5.311 <sect1 id="sec:collab:ssh"> 5.312 <title>Using the Secure Shell (ssh) protocol</title> 5.313 5.314 @@ -506,11 +551,11 @@ 5.315 protocol. To use this successfully, you may have to do a little 5.316 bit of configuration on the client or server sides.</para> 5.317 5.318 - <para id="x_487">If you're not familiar with ssh, it's a network protocol 5.319 - that lets you securely communicate with another computer. To 5.320 - use it with Mercurial, you'll be setting up one or more user 5.321 - accounts on a server so that remote users can log in and execute 5.322 - commands.</para> 5.323 + <para id="x_487">If you're not familiar with ssh, it's the name of 5.324 + both a command and a network protocol that let you securely 5.325 + communicate with another computer. To use it with Mercurial, 5.326 + you'll be setting up one or more user accounts on a server so 5.327 + that remote users can log in and execute commands.</para> 5.328 5.329 <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll 5.330 probably find some of the material that follows to be elementary 5.331 @@ -569,8 +614,8 @@ 5.332 <emphasis>absolute</emphasis> path on the server, begin the 5.333 path component with two slashes, as in this example.</para> 5.334 <programlisting>ssh://server//absolute/path</programlisting> 5.335 - 5.336 - </sect2> 5.337 + </sect2> 5.338 + 5.339 <sect2> 5.340 <title>Finding an ssh client for your system</title> 5.341 5.342 @@ -582,44 +627,44 @@ 5.343 unlikely event that it isn't present, take a look at your 5.344 system documentation to figure out how to install it.</para> 5.345 5.346 - <para id="x_494">On Windows, you'll first need to download a suitable ssh 5.347 - client. There are two alternatives.</para> 5.348 + <para id="x_494">On Windows, the TortoiseHg package is bundled 5.349 + with a version of Simon Tatham's excellent 5.350 + <command>plink</command> command, and you should not need to 5.351 + do any further configuration.</para> 5.352 + </sect2> 5.353 + 5.354 + <sect2> 5.355 + <title>Generating a key pair</title> 5.356 + 5.357 + <para id="x_499">To avoid the need to repetitively type a 5.358 + password every time you need to use your ssh client, I 5.359 + recommend generating a key pair.</para> 5.360 + 5.361 + <tip> 5.362 + <title>Key pairs are not mandatory</title> 5.363 + 5.364 + <para id="x_6a4">Mercurial knows nothing about ssh authentication or key 5.365 + pairs. You can, if you like, safely ignore this section and 5.366 + the one that follows until you grow tired of repeatedly 5.367 + typing ssh passwords.</para> 5.368 + </tip> 5.369 + 5.370 <itemizedlist> 5.371 - <listitem><para id="x_495">Simon Tatham's excellent PuTTY package 5.372 - <citation>web:putty</citation> provides a complete suite 5.373 - of ssh client commands.</para> 5.374 - </listitem> 5.375 - <listitem><para id="x_496">If you have a high tolerance for pain, you can 5.376 - use the Cygwin port of OpenSSH.</para> 5.377 - </listitem></itemizedlist> 5.378 - <para id="x_497">In either case, you'll need to edit your <filename 5.379 - role="special">hg.ini</filename> file to 5.380 - tell Mercurial where to find the actual client command. For 5.381 - example, if you're using PuTTY, you'll need to use the 5.382 - <command>plink</command> command as a command-line ssh 5.383 - client.</para> 5.384 - <programlisting>[ui] 5.385 -ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting> 5.386 - 5.387 - <note> 5.388 - <para id="x_498"> The path to <command>plink</command> shouldn't contain 5.389 - any whitespace characters, or Mercurial may not be able to 5.390 - run it correctly (so putting it in <filename 5.391 - class="directory">C:\Program Files</filename> is probably 5.392 - not a good idea).</para> 5.393 - </note> 5.394 - 5.395 - </sect2> 5.396 - <sect2> 5.397 - <title>Generating a key pair</title> 5.398 - 5.399 - <para id="x_499">To avoid the need to repetitively type a password every 5.400 - time you need to use your ssh client, I recommend generating a 5.401 - key pair. On a Unix-like system, the 5.402 - <command>ssh-keygen</command> command will do the trick. On 5.403 - Windows, if you're using PuTTY, the 5.404 - <command>puttygen</command> command is what you'll 5.405 - need.</para> 5.406 + <listitem> 5.407 + <para id="x_6a5">On a Unix-like system, the 5.408 + <command>ssh-keygen</command> command will do the 5.409 + trick.</para> 5.410 + <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need 5.411 + to download a command named <command>puttygen</command> 5.412 + from <ulink 5.413 + url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 5.414 + PuTTY web site</ulink> to generate a key pair. See 5.415 + <ulink 5.416 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 5.417 + <command>puttygen</command> documentation</ulink> for 5.418 + details of how use the command.</para> 5.419 + </listitem> 5.420 + </itemizedlist> 5.421 5.422 <para id="x_49a">When you generate a key pair, it's usually 5.423 <emphasis>highly</emphasis> advisable to protect it with a 5.424 @@ -642,7 +687,6 @@ 5.425 public key to a file of your choosing, or paste it from the 5.426 window it's displayed in straight into the <filename 5.427 role="special">authorized_keys</filename> file.</para> 5.428 - 5.429 </sect2> 5.430 <sect2> 5.431 <title>Using an authentication agent</title> 5.432 @@ -663,21 +707,34 @@ 5.433 judgment as to whether this is an acceptable risk. It 5.434 certainly saves a lot of repeated typing.</para> 5.435 5.436 - <para id="x_49f">On Unix-like systems, the agent is called 5.437 - <command>ssh-agent</command>, and it's often run automatically 5.438 - for you when you log in. You'll need to use the 5.439 - <command>ssh-add</command> command to add passphrases to the 5.440 - agent's store. On Windows, if you're using PuTTY, the 5.441 - <command>pageant</command> command acts as the agent. It adds 5.442 - an icon to your system tray that will let you manage stored 5.443 - passphrases.</para> 5.444 - 5.445 - </sect2> 5.446 + <itemizedlist> 5.447 + <listitem> 5.448 + <para id="x_49f">On Unix-like systems, the agent is called 5.449 + <command>ssh-agent</command>, and it's often run 5.450 + automatically for you when you log in. You'll need to use 5.451 + the <command>ssh-add</command> command to add passphrases 5.452 + to the agent's store.</para> 5.453 + </listitem> 5.454 + <listitem> 5.455 + <para id="x_6a7">On Windows, if you're using TortoiseHg, the 5.456 + <command>pageant</command> command acts as the agent. As 5.457 + with <command>puttygen</command>, you'll need to <ulink 5.458 + url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 5.459 + <command>pageant</command></ulink> from the PuTTY web 5.460 + site and read <ulink 5.461 + url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 5.462 + documentation</ulink>. The <command>pageant</command> 5.463 + command adds an icon to your system tray that will let you 5.464 + manage stored passphrases.</para> 5.465 + </listitem> 5.466 + </itemizedlist> 5.467 + </sect2> 5.468 + 5.469 <sect2> 5.470 <title>Configuring the server side properly</title> 5.471 5.472 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it, 5.473 - there's a variety of things that can go wrong. Add Mercurial 5.474 + a variety of things can go wrong. Add Mercurial 5.475 on top, and there's plenty more scope for head-scratching. 5.476 Most of these potential problems occur on the server side, not 5.477 the client side. The good news is that once you've gotten a 5.478 @@ -821,7 +878,6 @@ 5.479 If you run into problems with Mercurial and ssh at this point, 5.480 try using the <option role="hg-opt-global">--debug</option> 5.481 option to get a clearer picture of what's going on.</para> 5.482 - 5.483 </sect2> 5.484 <sect2> 5.485 <title>Using compression with ssh</title> 5.486 @@ -842,31 +898,40 @@ 5.487 accept a <option role="cmd-opt-ssh">-C</option> option which 5.488 turns on compression. You can easily edit your <filename 5.489 role="special">~/.hgrc</filename> to enable compression for 5.490 - all of Mercurial's uses of the ssh protocol.</para> 5.491 + all of Mercurial's uses of the ssh protocol. Here is how to 5.492 + do so for regular <command>ssh</command> on Unix-like systems, 5.493 + for example.</para> 5.494 <programlisting>[ui] 5.495 ssh = ssh -C</programlisting> 5.496 5.497 - <para id="x_4b9">If you use <command>ssh</command>, you can configure it to 5.498 - always use compression when talking to your server. To do 5.499 - this, edit your <filename 5.500 - role="special">.ssh/config</filename> file (which may not 5.501 - yet exist), as follows.</para> 5.502 + <para id="x_4b9">If you use <command>ssh</command> on a 5.503 + Unix-like system, you can configure it to always use 5.504 + compression when talking to your server. To do this, edit 5.505 + your <filename role="special">.ssh/config</filename> file 5.506 + (which may not yet exist), as follows.</para> 5.507 + 5.508 <programlisting>Host hg 5.509 Compression yes 5.510 HostName hg.example.com</programlisting> 5.511 - <para id="x_4ba">This defines an alias, <literal>hg</literal>. When you 5.512 - use it on the <command>ssh</command> command line or in a 5.513 - Mercurial <literal>ssh</literal>-protocol URL, it will cause 5.514 + 5.515 + <para id="x_4ba">This defines a hostname alias, 5.516 + <literal>hg</literal>. When you use that hostname on the 5.517 + <command>ssh</command> command line or in a Mercurial 5.518 + <literal>ssh</literal>-protocol URL, it will cause 5.519 <command>ssh</command> to connect to 5.520 <literal>hg.example.com</literal> and use compression. This 5.521 gives you both a shorter name to type and compression, each of 5.522 which is a good thing in its own right.</para> 5.523 - 5.524 </sect2> 5.525 </sect1> 5.526 + 5.527 <sect1 id="sec:collab:cgi"> 5.528 <title>Serving over HTTP using CGI</title> 5.529 5.530 + <para id="x_6a8">The simplest way to host one or more repositories in a 5.531 + permanent way is to use a web server and Mercurial's CGI 5.532 + support.</para> 5.533 + 5.534 <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's 5.535 CGI interface can take anything from a few moments to several 5.536 hours.</para> 5.537 @@ -877,13 +942,20 @@ 5.538 your web server's configuration.</para> 5.539 5.540 <note> 5.541 - <para id="x_4bd"> Configuring a web server is a complex, fiddly, and 5.542 - highly system-dependent activity. I can't possibly give you 5.543 - instructions that will cover anything like all of the cases 5.544 - you will encounter. Please use your discretion and judgment in 5.545 - following the sections below. Be prepared to make plenty of 5.546 - mistakes, and to spend a lot of time reading your server's 5.547 - error logs.</para> 5.548 + <title>High pain tolerance required</title> 5.549 + 5.550 + <para id="x_4bd">Configuring a web server is a complex, fiddly, 5.551 + and highly system-dependent activity. I can't possibly give 5.552 + you instructions that will cover anything like all of the 5.553 + cases you will encounter. Please use your discretion and 5.554 + judgment in following the sections below. Be prepared to make 5.555 + plenty of mistakes, and to spend a lot of time reading your 5.556 + server's error logs.</para> 5.557 + 5.558 + <para id="x_6a9">If you don't have a strong stomach for tweaking 5.559 + configurations over and over, or a compelling need to host 5.560 + your own services, you might want to try one of the public 5.561 + hosting services that I mentioned earlier.</para> 5.562 </note> 5.563 5.564 <sect2> 5.565 @@ -893,9 +965,10 @@ 5.566 aspects of your system's setup.</para> 5.567 5.568 <orderedlist> 5.569 - <listitem><para id="x_4bf">Do you have a web server installed at all? 5.570 - Mac OS X ships with Apache, but many other systems may not 5.571 - have a web server installed.</para> 5.572 + <listitem><para id="x_4bf">Do you have a web server installed 5.573 + at all? Mac OS X and some Linux distributions ship with 5.574 + Apache, but many other systems may not have a web server 5.575 + installed.</para> 5.576 </listitem> 5.577 <listitem><para id="x_4c0">If you have a web server installed, is it 5.578 actually running? On most systems, even if one is 5.579 @@ -917,8 +990,8 @@ 5.580 repositories. And <literal>lighttpd</literal> is undeniably 5.581 <emphasis>much</emphasis> easier to get started with than 5.582 Apache.</para> 5.583 - 5.584 - </sect2> 5.585 + </sect2> 5.586 + 5.587 <sect2> 5.588 <title>Basic CGI configuration</title> 5.589 5.590 @@ -1048,8 +1121,8 @@ 5.591 <para id="x_4d0">At this point, when you try to reload the page, you 5.592 should be presented with a nice HTML view of your 5.593 repository's history. Whew!</para> 5.594 - 5.595 </sect3> 5.596 + 5.597 <sect3> 5.598 <title>Configuring lighttpd</title> 5.599 5.600 @@ -1084,9 +1157,9 @@ 5.601 configure than Apache, even though I've used Apache for over 5.602 a decade, and this was my first exposure to 5.603 <literal>lighttpd</literal>.</para> 5.604 - 5.605 </sect3> 5.606 </sect2> 5.607 + 5.608 <sect2> 5.609 <title>Sharing multiple repositories with one CGI script</title> 5.610 5.611 @@ -1215,14 +1288,16 @@ 5.612 file.</para> 5.613 5.614 <note> 5.615 - <para id="x_4e2"> If multiple repositories have the same virtual path, 5.616 - <filename role="special">hgwebdir.cgi</filename> will not 5.617 - report an error. Instead, it will behave 5.618 - unpredictably.</para> 5.619 + <title>Beware duplicate virtual paths</title> 5.620 + 5.621 + <para id="x_4e2"> If several repositories have the same 5.622 + virtual path, <filename 5.623 + role="special">hgwebdir.cgi</filename> will not report 5.624 + an error. Instead, it will behave unpredictably.</para> 5.625 </note> 5.626 - 5.627 </sect3> 5.628 </sect2> 5.629 + 5.630 <sect2> 5.631 <title>Downloading source archives</title> 5.632 5.633 @@ -1235,8 +1310,7 @@ 5.634 you'll need to add an <envar 5.635 role="rc-item-web">allow_archive</envar> item to the 5.636 <literal role="rc-web">web</literal> section of your <filename 5.637 - role="special">~/.hgrc</filename>.</para> 5.638 - 5.639 + role="special">~/.hgrc</filename>; see below for details.</para> 5.640 </sect2> 5.641 <sect2> 5.642 <title>Web configuration options</title> 5.643 @@ -1318,9 +1392,28 @@ 5.644 <listitem><para id="x_4f0"><envar 5.645 role="rc-item-web">style</envar>: Controls the template 5.646 Mercurial uses to display the web interface. Mercurial 5.647 - ships with two web templates, named 5.648 - <literal>default</literal> and <literal>gitweb</literal> 5.649 - (the latter is much more visually attractive). You can 5.650 + ships with several web templates.</para> 5.651 + <itemizedlist> 5.652 + <listitem> 5.653 + <para id="x_6aa"><literal>coal</literal> is monochromatic.</para> 5.654 + </listitem> 5.655 + <listitem> 5.656 + <para id="x_6ab"><literal>gitweb</literal> emulates the visual 5.657 + style of git's web interface.</para> 5.658 + </listitem> 5.659 + <listitem> 5.660 + <para id="x_6ac"><literal>monoblue</literal> uses solid blues and 5.661 + greys.</para> 5.662 + </listitem> 5.663 + <listitem> 5.664 + <para id="x_6ad"><literal>paper</literal> is the default.</para> 5.665 + </listitem> 5.666 + <listitem> 5.667 + <para id="x_6ae"><literal>spartan</literal> was the default for a 5.668 + long time.</para> 5.669 + </listitem> 5.670 + </itemizedlist> 5.671 + <para id="x_6af">You can 5.672 also specify a custom template of your own; see 5.673 <xref linkend="chap:template"/> for details. Here, you can 5.674 see how to enable the <literal>gitweb</literal> 5.675 @@ -1361,8 +1454,8 @@ 5.676 interface. This overrides the default name, which is 5.677 the last component of the repository's path.</para> 5.678 </listitem></itemizedlist> 5.679 - 5.680 </sect3> 5.681 + 5.682 <sect3> 5.683 <title>Options specific to the <command role="hg-cmd">hg 5.684 serve</command> command</title> 5.685 @@ -1400,8 +1493,8 @@ 5.686 Integer. The TCP port number on which the server should 5.687 listen. The default port number used is 8000.</para> 5.688 </listitem></itemizedlist> 5.689 - 5.690 </sect3> 5.691 + 5.692 <sect3> 5.693 <title>Choosing the right <filename 5.694 role="special">~/.hgrc</filename> file to add <literal 5.695 @@ -1423,12 +1516,57 @@ 5.696 <filename role="special">~/.hgrc</filename> file in the 5.697 home directory of the user ID that runs your web server, or 5.698 add those settings to a system-wide <filename 5.699 - role="special">~/.hgrc</filename> file.</para> 5.700 - 5.701 - 5.702 + role="special">hgrc</filename> file.</para> 5.703 </sect3> 5.704 </sect2> 5.705 </sect1> 5.706 + 5.707 + <sect1> 5.708 + <title>System-wide configuration</title> 5.709 + 5.710 + <para id="x_6b0">On Unix-like systems shared by multiple users (such as a 5.711 + server to which people publish changes), it often makes sense to 5.712 + set up some global default behaviors, such as what theme to use 5.713 + in web interfaces.</para> 5.714 + 5.715 + <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename> 5.716 + exists, Mercurial will read it at startup time and apply any 5.717 + configuration settings it finds in that file. It will also look 5.718 + for files ending in a <literal>.rc</literal> extension in a 5.719 + directory named <filename>/etc/mercurial/hgrc.d</filename>, and 5.720 + apply any configuration settings it finds in each of those 5.721 + files.</para> 5.722 + 5.723 + <sect2> 5.724 + <title>Making Mercurial more trusting</title> 5.725 + 5.726 + <para id="x_6b2">One situation in which a global <filename>hgrc</filename> 5.727 + can be useful is if users are pulling changes owned by other 5.728 + users. By default, Mercurial will not trust most of the 5.729 + configuration items in a <filename>.hg/hgrc</filename> file 5.730 + inside a repository that is owned by a different user. If we 5.731 + clone or pull changes from such a repository, Mercurial will 5.732 + print a warning stating that it does not trust their 5.733 + <filename>.hg/hgrc</filename>.</para> 5.734 + 5.735 + <para id="x_6b3">If everyone in a particular Unix group is on the same team 5.736 + and <emphasis>should</emphasis> trust each other's 5.737 + configuration settings, or we want to trust particular users, 5.738 + we can override Mercurial's skeptical defaults by creating a 5.739 + system-wide <filename>hgrc</filename> file such as the 5.740 + following:</para> 5.741 + 5.742 + <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc 5.743 +[trusted] 5.744 +# Trust all entries in any hgrc file owned by the "editors" or 5.745 +# "www-data" groups. 5.746 +groups = editors, www-data 5.747 + 5.748 +# Trust entries in hgrc files owned by the following users. 5.749 +users = apache, bobo 5.750 +</programlisting> 5.751 + </sect2> 5.752 + </sect1> 5.753 </chapter> 5.754 5.755 <!--
6.1 --- a/en/ch06-filenames.xml Sat Apr 18 17:38:07 2009 +0200 6.2 +++ b/en/ch06-filenames.xml Sat Apr 18 17:45:54 2009 +0200 6.3 @@ -27,8 +27,8 @@ 6.4 before continuing with the current directory.</para> 6.5 6.6 &interaction.filenames.dirs; 6.7 - 6.8 - </sect1> 6.9 + </sect1> 6.10 + 6.11 <sect1> 6.12 <title>Running commands without any file names</title> 6.13 6.14 @@ -70,8 +70,8 @@ 6.15 role="hg-cmd">hg root</command> command.</para> 6.16 6.17 &interaction.filenames.wdir-relname; 6.18 - 6.19 - </sect1> 6.20 + </sect1> 6.21 + 6.22 <sect1> 6.23 <title>Telling you what's going on</title> 6.24 6.25 @@ -85,17 +85,17 @@ 6.26 <para id="x_54d">The principle here is of <emphasis>least 6.27 surprise</emphasis>. If you've exactly named a file on the 6.28 command line, there's no point in repeating it back at you. If 6.29 - Mercurial is acting on a file <emphasis>implicitly</emphasis>, 6.30 + Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g. 6.31 because you provided no names, or a directory, or a pattern (see 6.32 - below), it's safest to tell you what it's doing.</para> 6.33 + below), it is safest to tell you what files it's operating on.</para> 6.34 6.35 <para id="x_54e">For commands that behave this way, you can silence them 6.36 using the <option role="hg-opt-global">-q</option> option. You 6.37 can also get them to print the name of every file, even those 6.38 you've named explicitly, using the <option 6.39 role="hg-opt-global">-v</option> option.</para> 6.40 - 6.41 - </sect1> 6.42 + </sect1> 6.43 + 6.44 <sect1> 6.45 <title>Using patterns to identify files</title> 6.46 6.47 @@ -194,9 +194,9 @@ 6.48 example illustrates the difference between the two.</para> 6.49 6.50 &interaction.filenames.glob.star-starstar; 6.51 - 6.52 </sect3> 6.53 </sect2> 6.54 + 6.55 <sect2> 6.56 <title>Regular expression matching with <literal>re</literal> 6.57 patterns</title> 6.58 @@ -227,9 +227,9 @@ 6.59 string; it doesn't look for a match anywhere within the 6.60 string. To match anywhere in a string, start your pattern 6.61 with <quote><literal>.*</literal></quote>.</para> 6.62 - 6.63 </sect2> 6.64 </sect1> 6.65 + 6.66 <sect1> 6.67 <title>Filtering files</title> 6.68 6.69 @@ -266,14 +266,65 @@ 6.70 pattern</quote>.</para> 6.71 6.72 &interaction.filenames.filter.exclude; 6.73 - 6.74 - </sect1> 6.75 - <sect1> 6.76 - <title>Ignoring unwanted files and directories</title> 6.77 - 6.78 - <para id="x_569">XXX.</para> 6.79 - 6.80 - </sect1> 6.81 + </sect1> 6.82 + 6.83 + <sect1> 6.84 + <title>Permanently ignoring unwanted files and directories</title> 6.85 + 6.86 + <para id="x_569">When you create a new repository, the chances are 6.87 + that over time it will grow to contain files that ought to 6.88 + <emphasis>not</emphasis> be managed by Mercurial, but which you 6.89 + don't want to see listed every time you run <command>hg 6.90 + status</command>. For instance, <quote>build products</quote> 6.91 + are files that are created as part of a build but which should 6.92 + not be managed by a revision control system. The most common 6.93 + build products are output files produced by software tools such 6.94 + as compilers. As another example, many text editors litter a 6.95 + directory with lock files, temporary working files, and backup 6.96 + files, which it also makes no sense to manage.</para> 6.97 + 6.98 + <para id="x_6b4">To have Mercurial permanently ignore such files, create a 6.99 + file named <filename>.hgignore</filename> in the root of your 6.100 + repository. You <emphasis>should</emphasis> <command>hg 6.101 + add</command> this file so that it gets tracked with the rest of 6.102 + your repository contents, since your collaborators will probably 6.103 + find it useful too.</para> 6.104 + 6.105 + <para id="x_6b5">By default, the <filename>.hgignore</filename> file should 6.106 + contain a list of regular expressions, one per line. Empty 6.107 + lines are skipped. Most people prefer to describe the files they 6.108 + want to ignore using the <quote>glob</quote> syntax that we 6.109 + described above, so a typical <filename>.hgignore</filename> 6.110 + file will start with this directive:</para> 6.111 + 6.112 + <programlisting>syntax: glob</programlisting> 6.113 + 6.114 + <para id="x_6b6">This tells Mercurial to interpret the lines that follow as 6.115 + glob patterns, not regular expressions.</para> 6.116 + 6.117 + <para id="x_6b7">Here is a typical-looking <filename>.hgignore</filename> 6.118 + file.</para> 6.119 + 6.120 + <programlisting>syntax: glob 6.121 +# This line is a comment, and will be skipped. 6.122 +# Empty lines are skipped too. 6.123 + 6.124 +# Backup files left behind by the Emacs editor. 6.125 +*~ 6.126 + 6.127 +# Lock files used by the Emacs editor. 6.128 +# Notice that the "#" character is quoted with a backslash. 6.129 +# This prevents it from being interpreted as starting a comment. 6.130 +.\#* 6.131 + 6.132 +# Temporary files used by the vim editor. 6.133 +.*.swp 6.134 + 6.135 +# A hidden file created by the Mac OS X Finder. 6.136 +.DS_Store 6.137 +</programlisting> 6.138 + </sect1> 6.139 + 6.140 <sect1 id="sec:names:case"> 6.141 <title>Case sensitivity</title> 6.142 6.143 @@ -361,8 +412,8 @@ 6.144 conflict between the two file names that the filesystem would 6.145 treat as the same, and forbid the update or merge from 6.146 occurring.</para> 6.147 - 6.148 </sect2> 6.149 + 6.150 <sect2> 6.151 <title>Fixing a case conflict</title> 6.152 6.153 @@ -388,15 +439,6 @@ 6.154 <command role="hg-cmd">hg update</command> your working 6.155 directory to that changeset on a Windows or MacOS system, but 6.156 you can continue development unimpeded.</para> 6.157 - 6.158 - <note> 6.159 - <para id="x_577"> Prior to version 0.9.3, Mercurial did not use a case 6.160 - safe repository storage mechanism, and did not detect case 6.161 - folding conflicts. If you are using an older version of 6.162 - Mercurial on Windows or MacOS, I strongly recommend that you 6.163 - upgrade.</para> 6.164 - </note> 6.165 - 6.166 </sect2> 6.167 </sect1> 6.168 </chapter>
7.1 --- a/en/ch07-branch.xml Sat Apr 18 17:38:07 2009 +0200 7.2 +++ b/en/ch07-branch.xml Sat Apr 18 17:45:54 2009 +0200 7.3 @@ -128,7 +128,7 @@ 7.4 7.5 <para id="x_37c">Mercurial stores tags in a normal revision-controlled file 7.6 in your repository. If you've created any tags, you'll find 7.7 - them in a file named <filename 7.8 + them in a file in the root of your repository named <filename 7.9 role="special">.hgtags</filename>. When you run the <command 7.10 role="hg-cmd">hg tag</command> command, Mercurial modifies 7.11 this file, then automatically commits the change to it. This 7.12 @@ -170,8 +170,8 @@ 7.13 location of the error, which you can then fix and commit. You 7.14 should then run <command role="hg-cmd">hg tags</command> 7.15 again, just to be sure that your fix is correct.</para> 7.16 - 7.17 </sect2> 7.18 + 7.19 <sect2> 7.20 <title>Tags and cloning</title> 7.21 7.22 @@ -195,8 +195,8 @@ 7.23 project's history in the new repository, but 7.24 <emphasis>not</emphasis> the tag you might have 7.25 expected.</para> 7.26 - 7.27 </sect2> 7.28 + 7.29 <sect2> 7.30 <title>When permanent tags are too much</title> 7.31 7.32 @@ -221,9 +221,9 @@ 7.33 controlled. Any tags you create using <option 7.34 role="hg-opt-tag">-l</option> remain strictly local to the 7.35 repository you're currently working in.</para> 7.36 - 7.37 </sect2> 7.38 </sect1> 7.39 + 7.40 <sect1> 7.41 <title>The flow of changes&emdash;big picture vs. little</title> 7.42 7.43 @@ -252,8 +252,8 @@ 7.44 merging changes. They expose the narrative of how the code 7.45 was developed.</para> 7.46 </listitem></itemizedlist> 7.47 - 7.48 - </sect1> 7.49 + </sect1> 7.50 + 7.51 <sect1> 7.52 <title>Managing big-picture branches in repositories</title> 7.53 7.54 @@ -285,8 +285,8 @@ 7.55 the <literal>myproject</literal> repository.</para> 7.56 7.57 &interaction.branch-repo.new; 7.58 - 7.59 - </sect1> 7.60 + </sect1> 7.61 + 7.62 <sect1> 7.63 <title>Don't repeat yourself: merging across branches</title> 7.64 7.65 @@ -308,8 +308,8 @@ 7.66 push back to the main branch.</para> 7.67 7.68 &interaction.branch-repo.merge; 7.69 - 7.70 - </sect1> 7.71 + </sect1> 7.72 + 7.73 <sect1> 7.74 <title>Naming branches within one repository</title> 7.75 7.76 @@ -408,8 +408,8 @@ 7.77 <para id="x_39d">In practice, this is something you won't do very often, as 7.78 branch names tend to have fairly long lifetimes. (This isn't a 7.79 rule, just an observation.)</para> 7.80 - 7.81 - </sect1> 7.82 + </sect1> 7.83 + 7.84 <sect1> 7.85 <title>Dealing with multiple named branches in a 7.86 repository</title> 7.87 @@ -454,8 +454,8 @@ 7.88 introduces a new head.</para> 7.89 7.90 &interaction.branch-named.foo-commit; 7.91 - 7.92 - </sect1> 7.93 + </sect1> 7.94 + 7.95 <sect1> 7.96 <title>Branch names and merging</title> 7.97 7.98 @@ -496,8 +496,8 @@ 7.99 Mercurial will choose the <quote>right</quote> 7.100 (<literal>bleeding-edge</literal>) branch name when I pull and 7.101 merge from <literal>stable</literal>.</para> 7.102 - 7.103 - </sect1> 7.104 + </sect1> 7.105 + 7.106 <sect1> 7.107 <title>Branch naming is generally useful</title> 7.108 7.109 @@ -522,7 +522,6 @@ 7.110 /.hgrc</filename>.</para> 7.111 <programlisting>[hooks] 7.112 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting> 7.113 - 7.114 </sect1> 7.115 </chapter> 7.116