1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/po/zh.po	Thu Mar 12 15:53:01 2009 +0800
     1.3 @@ -0,0 +1,16518 @@
     1.4 +#
     1.5 +# Simplified Chinese translation for hgbook
     1.6 +# This file is distributed under the same license as the hgbook.
     1.7 +#
     1.8 +# Authors:
     1.9 +# Dongsheng Song <dongsheng.song@gmail.com>, 2009
    1.10 +#
    1.11 +# Update to new pot:
    1.12 +#    msgmerge --update zh.po svnbook.pot
    1.13 +#
    1.14 +# Check translation:
    1.15 +#    msgfmt --statistics -c -o zh.mo zh.po
    1.16 +#
    1.17 +# Please format your translation before commit:
    1.18 +#    msgcat --sort-by-file --width=80 -o zh_new.po zh.po
    1.19 +#    mv -f zh_new.po zh.po
    1.20 +#
    1.21 +# Dictionary:
    1.22 +# blame             追溯
    1.23 +# branch            分支
    1.24 +# changes           修改
    1.25 +# changeset         修改集
    1.26 +# checkout          检出
    1.27 +# remove            移除(从版本库删除)
    1.28 +# delete            删除(只从文件系统删除)
    1.29 +# patchset          补丁集
    1.30 +# pushing to        推到
    1.31 +# pulling from      拉自
    1.32 +# rename            改名
    1.33 +# repository        版本库
    1.34 +# revert            恢复
    1.35 +# revision          版本
    1.36 +# tag               标签
    1.37 +# tip               顶点
    1.38 +# undo              撤销
    1.39 +# unversioned       未版本控制
    1.40 +# versioned         受版本控制
    1.41 +# working copy      工作副本
    1.42 +# ...
    1.43 +#
    1.44 +msgid ""
    1.45 +msgstr ""
    1.46 +"Project-Id-Version: hgbook 1.2\n"
    1.47 +"POT-Creation-Date: 2009-03-11 10:07+0800\n"
    1.48 +"PO-Revision-Date: 2009-03-09 23:32+0800\n"
    1.49 +"Last-Translator: \n"
    1.50 +"Language-Team: Simplified Chinese <i18n-zh@googlegroups.com >\n"
    1.51 +"MIME-Version: 1.0\n"
    1.52 +"Content-Type: text/plain; charset=UTF-8\n"
    1.53 +"Content-Transfer-Encoding: 8bit\n"
    1.54 +"X-Poedit-Language: Chinese\n"
    1.55 +"X-Poedit-Country: CHINA\n"
    1.56 +"X-Poedit-SourceCharset: utf-8\n"
    1.57 +
    1.58 +#. type: Content of: <book><title>
    1.59 +#: ../en/00book.xml:41
    1.60 +msgid "Mercurial: The Definitive Guide"
    1.61 +msgstr "Mercurial 权威指南"
    1.62 +
    1.63 +#. type: Content of: <book><subtitle>
    1.64 +#: ../en/00book.xml:46
    1.65 +msgid "Compiled from $rev_id$"
    1.66 +msgstr "编译自 $rev_id$"
    1.67 +
    1.68 +#. type: Content of: <book><bookinfo><authorgroup><author><firstname>
    1.69 +#: ../en/00book.xml:50
    1.70 +msgid "Bryan"
    1.71 +msgstr ""
    1.72 +
    1.73 +#. type: Content of: <book><bookinfo><authorgroup><author><surname>
    1.74 +#: ../en/00book.xml:51
    1.75 +msgid "O'Sullivan"
    1.76 +msgstr ""
    1.77 +
    1.78 +#. type: Content of: <book><bookinfo>
    1.79 +#: ../en/00book.xml:55
    1.80 +msgid ""
    1.81 +"<editor> <firstname>Mike</firstname> <surname>Loukides</surname> </editor> "
    1.82 +"<copyright> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</"
    1.83 +"year> <holder>Bryan O'Sullivan</holder> </copyright>"
    1.84 +msgstr ""
    1.85 +
    1.86 +#. type: Content of: <book><appendix><title>
    1.87 +#: ../en/appA-cmdref.xml:4
    1.88 +msgid "Command reference"
    1.89 +msgstr "命令参考"
    1.90 +
    1.91 +#. type: Content of: <book><appendix><para>
    1.92 +#: ../en/appA-cmdref.xml:6
    1.93 +msgid ""
    1.94 +"\\cmdref{add}{add files at the next commit} \\optref{add}{I}{include} \\optref"
    1.95 +"{add}{X}{exclude} \\optref{add}{n}{dry-run}"
    1.96 +msgstr ""
    1.97 +
    1.98 +#. type: Content of: <book><appendix><para>
    1.99 +#: ../en/appA-cmdref.xml:11
   1.100 +msgid "\\cmdref{diff}{print changes in history or working directory}"
   1.101 +msgstr ""
   1.102 +
   1.103 +#. type: Content of: <book><appendix><para>
   1.104 +#: ../en/appA-cmdref.xml:13
   1.105 +msgid ""
   1.106 +"Show differences between revisions for the specified files or directories, "
   1.107 +"using the unified diff format.  For a description of the unified diff format, "
   1.108 +"see section <xref linkend=\"sec.mq.patch\"/>."
   1.109 +msgstr ""
   1.110 +
   1.111 +#. type: Content of: <book><appendix><para>
   1.112 +#: ../en/appA-cmdref.xml:17
   1.113 +msgid ""
   1.114 +"By default, this command does not print diffs for files that Mercurial "
   1.115 +"considers to contain binary data.  To control this behaviour, see the <option "
   1.116 +"role=\"hg-opt-diff\">-a</option> and <option role=\"hg-opt-diff\">--git</"
   1.117 +"option> options."
   1.118 +msgstr ""
   1.119 +
   1.120 +#. type: Content of: <book><appendix><sect2><title>
   1.121 +#: ../en/appA-cmdref.xml:22
   1.122 +msgid "Options"
   1.123 +msgstr "选项"
   1.124 +
   1.125 +#. type: Content of: <book><appendix><sect2><para>
   1.126 +#: ../en/appA-cmdref.xml:24
   1.127 +msgid "\\loptref{diff}{nodates}"
   1.128 +msgstr ""
   1.129 +
   1.130 +#. type: Content of: <book><appendix><sect2><para>
   1.131 +#: ../en/appA-cmdref.xml:26
   1.132 +msgid "Omit date and time information when printing diff headers."
   1.133 +msgstr ""
   1.134 +
   1.135 +#. type: Content of: <book><appendix><sect2><para>
   1.136 +#: ../en/appA-cmdref.xml:28
   1.137 +msgid "\\optref{diff}{B}{ignore-blank-lines}"
   1.138 +msgstr ""
   1.139 +
   1.140 +#. type: Content of: <book><appendix><sect2><para>
   1.141 +#: ../en/appA-cmdref.xml:30
   1.142 +msgid ""
   1.143 +"Do not print changes that only insert or delete blank lines.  A line that "
   1.144 +"contains only whitespace is not considered blank."
   1.145 +msgstr ""
   1.146 +
   1.147 +#. type: Content of: <book><appendix><sect2><para>
   1.148 +#: ../en/appA-cmdref.xml:34
   1.149 +msgid "\\optref{diff}{I}{include}"
   1.150 +msgstr ""
   1.151 +
   1.152 +#. type: Content of: <book><appendix><sect2><para>
   1.153 +#: ../en/appA-cmdref.xml:37
   1.154 +msgid "Include files and directories whose names match the given patterns."
   1.155 +msgstr ""
   1.156 +
   1.157 +#. type: Content of: <book><appendix><sect2><para>
   1.158 +#: ../en/appA-cmdref.xml:40
   1.159 +msgid "\\optref{diff}{X}{exclude}"
   1.160 +msgstr ""
   1.161 +
   1.162 +#. type: Content of: <book><appendix><sect2><para>
   1.163 +#: ../en/appA-cmdref.xml:43
   1.164 +msgid "Exclude files and directories whose names match the given patterns."
   1.165 +msgstr ""
   1.166 +
   1.167 +#. type: Content of: <book><appendix><sect2><para>
   1.168 +#: ../en/appA-cmdref.xml:46
   1.169 +msgid "\\optref{diff}{a}{text}"
   1.170 +msgstr ""
   1.171 +
   1.172 +#. type: Content of: <book><appendix><sect2><para>
   1.173 +#: ../en/appA-cmdref.xml:49
   1.174 +msgid ""
   1.175 +"If this option is not specified, <command role=\"hg-cmd\">hg diff</command> "
   1.176 +"will refuse to print diffs for files that it detects as binary. Specifying "
   1.177 +"<option role=\"hg-opt-diff\">-a</option> forces <command role=\"hg-cmd\">hg "
   1.178 +"diff</command> to treat all files as text, and generate diffs for all of them."
   1.179 +msgstr ""
   1.180 +
   1.181 +#. type: Content of: <book><appendix><sect2><para>
   1.182 +#: ../en/appA-cmdref.xml:55
   1.183 +msgid ""
   1.184 +"This option is useful for files that are <quote>mostly text</quote> but have "
   1.185 +"a few embedded NUL characters.  If you use it on files that contain a lot of "
   1.186 +"binary data, its output will be incomprehensible."
   1.187 +msgstr ""
   1.188 +
   1.189 +#. type: Content of: <book><appendix><sect2><para>
   1.190 +#: ../en/appA-cmdref.xml:60
   1.191 +msgid "\\optref{diff}{b}{ignore-space-change}"
   1.192 +msgstr ""
   1.193 +
   1.194 +#. type: Content of: <book><appendix><sect2><para>
   1.195 +#: ../en/appA-cmdref.xml:63
   1.196 +msgid ""
   1.197 +"Do not print a line if the only change to that line is in the amount of white "
   1.198 +"space it contains."
   1.199 +msgstr ""
   1.200 +
   1.201 +#. type: Content of: <book><appendix><sect2><para>
   1.202 +#: ../en/appA-cmdref.xml:67
   1.203 +msgid "\\optref{diff}{g}{git}"
   1.204 +msgstr ""
   1.205 +
   1.206 +#. type: Content of: <book><appendix><sect2><para>
   1.207 +#: ../en/appA-cmdref.xml:70
   1.208 +msgid ""
   1.209 +"Print <command>git</command>-compatible diffs.  XXX reference a format "
   1.210 +"description."
   1.211 +msgstr ""
   1.212 +
   1.213 +#. type: Content of: <book><appendix><sect2><para>
   1.214 +#: ../en/appA-cmdref.xml:74
   1.215 +msgid "\\optref{diff}{p}{show-function}"
   1.216 +msgstr ""
   1.217 +
   1.218 +#. type: Content of: <book><appendix><sect2><para>
   1.219 +#: ../en/appA-cmdref.xml:77
   1.220 +msgid ""
   1.221 +"Display the name of the enclosing function in a hunk header, using a simple "
   1.222 +"heuristic.  This functionality is enabled by default, so the <option role="
   1.223 +"\"hg-opt-diff\">-p</option> option has no effect unless you change the value "
   1.224 +"of the <envar role=\"rc-item-diff\">showfunc</envar> config item, as in the "
   1.225 +"following example."
   1.226 +msgstr ""
   1.227 +
   1.228 +#. type: Content of: <book><appendix><sect2><para>
   1.229 +#: ../en/appA-cmdref.xml:84
   1.230 +msgid "\\optref{diff}{r}{rev}"
   1.231 +msgstr ""
   1.232 +
   1.233 +#. type: Content of: <book><appendix><sect2><para>
   1.234 +#: ../en/appA-cmdref.xml:87
   1.235 +msgid ""
   1.236 +"Specify one or more revisions to compare.  The <command role=\"hg-cmd\">hg "
   1.237 +"diff</command> command accepts up to two <option role=\"hg-opt-diff\">-r</"
   1.238 +"option> options to specify the revisions to compare."
   1.239 +msgstr ""
   1.240 +
   1.241 +#. type: Content of: <book><appendix><sect2><orderedlist><listitem><para>
   1.242 +#: ../en/appA-cmdref.xml:93
   1.243 +msgid ""
   1.244 +"Display the differences between the parent revision of the working directory "
   1.245 +"and the working directory."
   1.246 +msgstr ""
   1.247 +
   1.248 +#. type: Content of: <book><appendix><sect2><orderedlist><listitem><para>
   1.249 +#: ../en/appA-cmdref.xml:97
   1.250 +msgid ""
   1.251 +"Display the differences between the specified changeset and the working "
   1.252 +"directory."
   1.253 +msgstr ""
   1.254 +
   1.255 +#. type: Content of: <book><appendix><sect2><orderedlist><listitem><para>
   1.256 +#: ../en/appA-cmdref.xml:101
   1.257 +msgid "Display the differences between the two specified changesets."
   1.258 +msgstr ""
   1.259 +
   1.260 +#. type: Content of: <book><appendix><sect2><para>
   1.261 +#: ../en/appA-cmdref.xml:105
   1.262 +msgid ""
   1.263 +"You can specify two revisions using either two <option role=\"hg-opt-diff\">-"
   1.264 +"r</option> options or revision range notation.  For example, the two revision "
   1.265 +"specifications below are equivalent."
   1.266 +msgstr ""
   1.267 +
   1.268 +#. type: Content of: <book><appendix><sect2><para>
   1.269 +#: ../en/appA-cmdref.xml:112
   1.270 +msgid ""
   1.271 +"When you provide two revisions, Mercurial treats the order of those revisions "
   1.272 +"as significant.  Thus, <command role=\"hg-cmd\">hg diff -r10:20</command> "
   1.273 +"will produce a diff that will transform files from their contents as of "
   1.274 +"revision 10 to their contents as of revision 20, while <command role=\"hg-cmd"
   1.275 +"\">hg diff -r20:10</command> means the opposite: the diff that will transform "
   1.276 +"files from their revision 20 contents to their revision 10 contents.  You "
   1.277 +"cannot reverse the ordering in this way if you are diffing against the "
   1.278 +"working directory."
   1.279 +msgstr ""
   1.280 +
   1.281 +#. type: Content of: <book><appendix><sect2><para>
   1.282 +#: ../en/appA-cmdref.xml:122
   1.283 +msgid "\\optref{diff}{w}{ignore-all-space}"
   1.284 +msgstr ""
   1.285 +
   1.286 +#. type: Content of: <book><appendix><sect2><para>
   1.287 +#: ../en/appA-cmdref.xml:125
   1.288 +msgid "\\cmdref{version}{print version and copyright information}"
   1.289 +msgstr ""
   1.290 +
   1.291 +#. type: Content of: <book><appendix><sect2><para>
   1.292 +#: ../en/appA-cmdref.xml:128
   1.293 +msgid ""
   1.294 +"This command displays the version of Mercurial you are running, and its "
   1.295 +"copyright license.  There are four kinds of version string that you may see."
   1.296 +msgstr ""
   1.297 +
   1.298 +#. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para>
   1.299 +#: ../en/appA-cmdref.xml:133
   1.300 +msgid ""
   1.301 +"The string <quote><literal>unknown</literal></quote>. This version of "
   1.302 +"Mercurial was not built in a Mercurial repository, and cannot determine its "
   1.303 +"own version."
   1.304 +msgstr ""
   1.305 +
   1.306 +#. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para>
   1.307 +#: ../en/appA-cmdref.xml:138
   1.308 +msgid ""
   1.309 +"A short numeric string, such as <quote><literal>1.1</literal></quote>. This "
   1.310 +"is a build of a revision of Mercurial that was identified by a specific tag "
   1.311 +"in the repository where it was built.  (This doesn't necessarily mean that "
   1.312 +"you're running an official release; someone else could have added that tag to "
   1.313 +"any revision in the repository where they built Mercurial.)"
   1.314 +msgstr ""
   1.315 +
   1.316 +#. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para>
   1.317 +#: ../en/appA-cmdref.xml:146
   1.318 +msgid ""
   1.319 +"A hexadecimal string, such as <quote><literal>875489e31abe</literal></"
   1.320 +"quote>.  This is a build of the given revision of Mercurial."
   1.321 +msgstr ""
   1.322 +
   1.323 +#. type: Content of: <book><appendix><sect2><itemizedlist><listitem><para>
   1.324 +#: ../en/appA-cmdref.xml:150
   1.325 +msgid ""
   1.326 +"A hexadecimal string followed by a date, such as <quote><literal>875489e31abe"
   1.327 +"+20070205</literal></quote>.  This is a build of the given revision of "
   1.328 +"Mercurial, where the build repository contained some local changes that had "
   1.329 +"not been committed."
   1.330 +msgstr ""
   1.331 +
   1.332 +#. type: Content of: <book><appendix><sect2><title>
   1.333 +#: ../en/appA-cmdref.xml:159
   1.334 +msgid "Tips and tricks"
   1.335 +msgstr ""
   1.336 +
   1.337 +#. type: Content of: <book><appendix><sect2><sect3><title>
   1.338 +#: ../en/appA-cmdref.xml:162
   1.339 +msgid ""
   1.340 +"Why do the results of <command role=\"hg-cmd\">hg diff</command> and <command "
   1.341 +"role=\"hg-cmd\">hg status</command> differ?"
   1.342 +msgstr ""
   1.343 +"为什么 <command role=\"hg-cmd\">hg diff</command> 与 <command role=\"hg-cmd"
   1.344 +"\">hg status</command> 的结果不同 ?"
   1.345 +
   1.346 +#. type: Content of: <book><appendix><sect2><sect3><para>
   1.347 +#: ../en/appA-cmdref.xml:164
   1.348 +msgid ""
   1.349 +"When you run the <command role=\"hg-cmd\">hg status</command> command, you'll "
   1.350 +"see a list of files that Mercurial will record changes for the next time you "
   1.351 +"perform a commit.  If you run the <command role=\"hg-cmd\">hg diff</command> "
   1.352 +"command, you may notice that it prints diffs for only a <emphasis>subset</"
   1.353 +"emphasis> of the files that <command role=\"hg-cmd\">hg status</command> "
   1.354 +"listed.  There are two possible reasons for this."
   1.355 +msgstr ""
   1.356 +
   1.357 +#. type: Content of: <book><appendix><sect2><sect3><para>
   1.358 +#: ../en/appA-cmdref.xml:171
   1.359 +msgid ""
   1.360 +"The first is that <command role=\"hg-cmd\">hg status</command> prints some "
   1.361 +"kinds of modifications that <command role=\"hg-cmd\">hg diff</command> "
   1.362 +"doesn't normally display.  The <command role=\"hg-cmd\">hg diff</command> "
   1.363 +"command normally outputs unified diffs, which don't have the ability to "
   1.364 +"represent some changes that Mercurial can track.  Most notably, traditional "
   1.365 +"diffs can't represent a change in whether or not a file is executable, but "
   1.366 +"Mercurial records this information."
   1.367 +msgstr ""
   1.368 +
   1.369 +#. type: Content of: <book><appendix><sect2><sect3><para>
   1.370 +#: ../en/appA-cmdref.xml:179
   1.371 +msgid ""
   1.372 +"If you use the <option role=\"hg-opt-diff\">--git</option> option to <command "
   1.373 +"role=\"hg-cmd\">hg diff</command>, it will display <command>git</command>-"
   1.374 +"compatible diffs that <emphasis>can</emphasis> display this extra information."
   1.375 +msgstr ""
   1.376 +
   1.377 +#. type: Content of: <book><appendix><sect2><sect3><para>
   1.378 +#: ../en/appA-cmdref.xml:184
   1.379 +msgid ""
   1.380 +"The second possible reason that <command role=\"hg-cmd\">hg diff</command> "
   1.381 +"might be printing diffs for a subset of the files displayed by <command role="
   1.382 +"\"hg-cmd\">hg status</command> is that if you invoke it without any "
   1.383 +"arguments, <command role=\"hg-cmd\">hg diff</command> prints diffs against "
   1.384 +"the first parent of the working directory.  If you have run <command role="
   1.385 +"\"hg-cmd\">hg merge</command> to merge two changesets, but you haven't yet "
   1.386 +"committed the results of the merge, your working directory has two parents "
   1.387 +"(use <command role=\"hg-cmd\">hg parents</command> to see them).  While "
   1.388 +"<command role=\"hg-cmd\">hg status</command> prints modifications relative to "
   1.389 +"<emphasis>both</emphasis> parents after an uncommitted merge, <command role="
   1.390 +"\"hg-cmd\">hg diff</command> still operates relative only to the first "
   1.391 +"parent.  You can get it to print diffs relative to the second parent by "
   1.392 +"specifying that parent with the <option role=\"hg-opt-diff\">-r</option> "
   1.393 +"option.  There is no way to print diffs relative to both parents."
   1.394 +msgstr ""
   1.395 +
   1.396 +#. type: Content of: <book><appendix><sect2><sect3><title>
   1.397 +#: ../en/appA-cmdref.xml:200
   1.398 +msgid "Generating safe binary diffs"
   1.399 +msgstr "生成安全的二进制差异"
   1.400 +
   1.401 +#. type: Content of: <book><appendix><sect2><sect3><para>
   1.402 +#: ../en/appA-cmdref.xml:202
   1.403 +msgid ""
   1.404 +"If you use the <option role=\"hg-opt-diff\">-a</option> option to force "
   1.405 +"Mercurial to print diffs of files that are either <quote>mostly text</quote> "
   1.406 +"or contain lots of binary data, those diffs cannot subsequently be applied by "
   1.407 +"either Mercurial's <command role=\"hg-cmd\">hg import</command> command or "
   1.408 +"the system's <command>patch</command> command."
   1.409 +msgstr ""
   1.410 +
   1.411 +#. type: Content of: <book><appendix><sect2><sect3><para>
   1.412 +#: ../en/appA-cmdref.xml:209
   1.413 +msgid ""
   1.414 +"If you want to generate a diff of a binary file that is safe to use as input "
   1.415 +"for <command role=\"hg-cmd\">hg import</command>, use the <command role=\"hg-"
   1.416 +"cmd\">hg diff</command>{--git} option when you generate the patch.  The "
   1.417 +"system <command>patch</command> command cannot handle binary patches at all."
   1.418 +msgstr ""
   1.419 +
   1.420 +#. type: Content of: <book><appendix><title>
   1.421 +#: ../en/appB-mq-ref.xml:5
   1.422 +msgid "Mercurial Queues reference"
   1.423 +msgstr "Mercurial 队列参考"
   1.424 +
   1.425 +#. type: Content of: <book><appendix><sect1><title>
   1.426 +#: ../en/appB-mq-ref.xml:8
   1.427 +msgid "MQ command reference"
   1.428 +msgstr "MQ 命令参考"
   1.429 +
   1.430 +#. type: Content of: <book><appendix><sect1><para>
   1.431 +#: ../en/appB-mq-ref.xml:10
   1.432 +msgid ""
   1.433 +"For an overview of the commands provided by MQ, use the command <command role="
   1.434 +"\"hg-cmd\">hg help mq</command>."
   1.435 +msgstr ""
   1.436 +
   1.437 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.438 +#: ../en/appB-mq-ref.xml:14
   1.439 +msgid ""
   1.440 +"<command role=\"hg-ext-mq\">qapplied</command>&emdash;print applied patches"
   1.441 +msgstr "<command role=\"hg-ext-mq\">qapplied</command>&emdash;显示已应用的补丁"
   1.442 +
   1.443 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.444 +#: ../en/appB-mq-ref.xml:17
   1.445 +msgid ""
   1.446 +"The <command role=\"hg-ext-mq\">qapplied</command> command prints the current "
   1.447 +"stack of applied patches.  Patches are printed in oldest-to-newest order, so "
   1.448 +"the last patch in the list is the <quote>top</quote> patch."
   1.449 +msgstr ""
   1.450 +
   1.451 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.452 +#: ../en/appB-mq-ref.xml:24
   1.453 +msgid ""
   1.454 +"<command role=\"hg-ext-mq\">qcommit</command>&emdash;commit changes in the "
   1.455 +"queue repository"
   1.456 +msgstr "<command role=\"hg-ext-mq\">qcommit</command>&emdash;提交队列中的修改"
   1.457 +
   1.458 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.459 +#: ../en/appB-mq-ref.xml:27
   1.460 +msgid ""
   1.461 +"The <command role=\"hg-ext-mq\">qcommit</command> command commits any "
   1.462 +"outstanding changes in the <filename role=\"special\" class=\"directory\">.hg/"
   1.463 +"patches</filename> repository.  This command only works if the <filename role="
   1.464 +"\"special\" class=\"directory\">.hg/patches</filename> directory is a "
   1.465 +"repository, i.e. you created the directory using <command role=\"hg-cmd\">hg "
   1.466 +"qinit <option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option></command> or ran "
   1.467 +"<command role=\"hg-cmd\">hg init</command> in the directory after running "
   1.468 +"<command role=\"hg-ext-mq\">qinit</command>."
   1.469 +msgstr ""
   1.470 +
   1.471 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.472 +#: ../en/appB-mq-ref.xml:39
   1.473 +msgid ""
   1.474 +"This command is shorthand for <command role=\"hg-cmd\">hg commit --cwd .hg/"
   1.475 +"patches</command>."
   1.476 +msgstr ""
   1.477 +
   1.478 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.479 +#: ../en/appB-mq-ref.xml:42
   1.480 +msgid ""
   1.481 +"\\subsection{<command role=\"hg-ext-mq\">qdelete</command>&emdash;delete a "
   1.482 +"patch from the <filename role=\"special\">series</filename> file}"
   1.483 +msgstr ""
   1.484 +
   1.485 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.486 +#: ../en/appB-mq-ref.xml:47
   1.487 +msgid ""
   1.488 +"The <command role=\"hg-ext-mq\">qdelete</command> command removes the entry "
   1.489 +"for a patch from the <filename role=\"special\">series</filename> file in the "
   1.490 +"<filename role=\"special\" class=\"directory\">.hg/patches</filename> "
   1.491 +"directory.  It does not pop the patch if the patch is already applied.  By "
   1.492 +"default, it does not delete the patch file; use the <option role=\"hg-ext-mq-"
   1.493 +"cmd-qdel-opt\">-f</option> option to do that."
   1.494 +msgstr ""
   1.495 +
   1.496 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.497 +#: ../en/appB-mq-ref.xml:56 ../en/appB-mq-ref.xml:98 ../en/appB-mq-ref.xml:156
   1.498 +#: ../en/appB-mq-ref.xml:196 ../en/appB-mq-ref.xml:263
   1.499 +#: ../en/appB-mq-ref.xml:334 ../en/appB-mq-ref.xml:403
   1.500 +#: ../en/appB-mq-ref.xml:496
   1.501 +msgid "Options:"
   1.502 +msgstr ""
   1.503 +
   1.504 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.505 +#: ../en/appB-mq-ref.xml:58
   1.506 +msgid ""
   1.507 +"<option role=\"hg-ext-mq-cmd-qdel-opt\">-f</option>: Delete the patch file."
   1.508 +msgstr ""
   1.509 +
   1.510 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.511 +#: ../en/appB-mq-ref.xml:65
   1.512 +msgid ""
   1.513 +"<command role=\"hg-ext-mq\">qdiff</command>&emdash;print a diff of the "
   1.514 +"topmost applied patch"
   1.515 +msgstr ""
   1.516 +"<command role=\"hg-ext-mq\">qdiff</command>&emdash;显示最新应用补丁的差异"
   1.517 +
   1.518 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.519 +#: ../en/appB-mq-ref.xml:68
   1.520 +msgid ""
   1.521 +"The <command role=\"hg-ext-mq\">qdiff</command> command prints a diff of the "
   1.522 +"topmost applied patch. It is equivalent to <command role=\"hg-cmd\">hg diff -"
   1.523 +"r-2:-1</command>."
   1.524 +msgstr ""
   1.525 +
   1.526 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.527 +#: ../en/appB-mq-ref.xml:74
   1.528 +msgid ""
   1.529 +"<command role=\"hg-ext-mq\">qfold</command>&emdash;merge (<quote>fold</"
   1.530 +"quote>) several patches into one"
   1.531 +msgstr ""
   1.532 +"<command role=\"hg-ext-mq\">qfold</command>&emdash;将多个补丁合并(<quote>折叠"
   1.533 +"</quote>)成一个"
   1.534 +
   1.535 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.536 +#: ../en/appB-mq-ref.xml:77
   1.537 +msgid ""
   1.538 +"The <command role=\"hg-ext-mq\">qfold</command> command merges multiple "
   1.539 +"patches into the topmost applied patch, so that the topmost applied patch "
   1.540 +"makes the union of all of the changes in the patches in question."
   1.541 +msgstr ""
   1.542 +
   1.543 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.544 +#: ../en/appB-mq-ref.xml:82
   1.545 +msgid ""
   1.546 +"The patches to fold must not be applied; <command role=\"hg-ext-mq\">qfold</"
   1.547 +"command> will exit with an error if any is.  The order in which patches are "
   1.548 +"folded is significant; <command role=\"hg-cmd\">hg qfold a b</command> means "
   1.549 +"<quote>apply the current topmost patch, followed by <literal>a</literal>, "
   1.550 +"followed by <literal>b</literal></quote>."
   1.551 +msgstr ""
   1.552 +
   1.553 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.554 +#: ../en/appB-mq-ref.xml:90
   1.555 +msgid ""
   1.556 +"The comments from the folded patches are appended to the comments of the "
   1.557 +"destination patch, with each block of comments separated by three asterisk "
   1.558 +"(<quote><literal>*</literal></quote>) characters.  Use the <option role=\"hg-"
   1.559 +"ext-mq-cmd-qfold-opt\">-e</option> option to edit the commit message for the "
   1.560 +"combined patch/changeset after the folding has completed."
   1.561 +msgstr ""
   1.562 +
   1.563 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.564 +#: ../en/appB-mq-ref.xml:100
   1.565 +msgid ""
   1.566 +"<option role=\"hg-ext-mq-cmd-qfold-opt\">-e</option>: Edit the commit message "
   1.567 +"and patch description for the newly folded patch."
   1.568 +msgstr ""
   1.569 +
   1.570 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.571 +#: ../en/appB-mq-ref.xml:105
   1.572 +msgid ""
   1.573 +"<option role=\"hg-ext-mq-cmd-qfold-opt\">-l</option>: Use the contents of the "
   1.574 +"given file as the new commit message and patch description for the folded "
   1.575 +"patch."
   1.576 +msgstr ""
   1.577 +
   1.578 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.579 +#: ../en/appB-mq-ref.xml:110
   1.580 +msgid ""
   1.581 +"<option role=\"hg-ext-mq-cmd-qfold-opt\">-m</option>: Use the given text as "
   1.582 +"the new commit message and patch description for the folded patch."
   1.583 +msgstr ""
   1.584 +
   1.585 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.586 +#: ../en/appB-mq-ref.xml:118
   1.587 +msgid ""
   1.588 +"<command role=\"hg-ext-mq\">qheader</command>&emdash;display the header/"
   1.589 +"description of a patch"
   1.590 +msgstr "<command role=\"hg-ext-mq\">qheader</command>&emdash;显示补丁头部描述"
   1.591 +
   1.592 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.593 +#: ../en/appB-mq-ref.xml:122
   1.594 +msgid ""
   1.595 +"The <command role=\"hg-ext-mq\">qheader</command> command prints the header, "
   1.596 +"or description, of a patch.  By default, it prints the header of the topmost "
   1.597 +"applied patch. Given an argument, it prints the header of the named patch."
   1.598 +msgstr ""
   1.599 +
   1.600 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.601 +#: ../en/appB-mq-ref.xml:129
   1.602 +msgid ""
   1.603 +"<command role=\"hg-ext-mq\">qimport</command>&emdash;import a third-party "
   1.604 +"patch into the queue"
   1.605 +msgstr ""
   1.606 +"<command role=\"hg-ext-mq\">qimport</command>&emdash;将第三方补丁导入队列"
   1.607 +
   1.608 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.609 +#: ../en/appB-mq-ref.xml:132
   1.610 +msgid ""
   1.611 +"The <command role=\"hg-ext-mq\">qimport</command> command adds an entry for "
   1.612 +"an external patch to the <filename role=\"special\">series</filename> file, "
   1.613 +"and copies the patch into the <filename role=\"special\" class=\"directory\">."
   1.614 +"hg/patches</filename> directory.  It adds the entry immediately after the "
   1.615 +"topmost applied patch, but does not push the patch."
   1.616 +msgstr ""
   1.617 +
   1.618 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.619 +#: ../en/appB-mq-ref.xml:140
   1.620 +msgid ""
   1.621 +"If the <filename role=\"special\" class=\"directory\">.hg/patches</filename> "
   1.622 +"directory is a repository, <command role=\"hg-ext-mq\">qimport</command> "
   1.623 +"automatically does an <command role=\"hg-cmd\">hg add</command> of the "
   1.624 +"imported patch."
   1.625 +msgstr ""
   1.626 +
   1.627 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.628 +#: ../en/appB-mq-ref.xml:148
   1.629 +msgid ""
   1.630 +"<command role=\"hg-ext-mq\">qinit</command>&emdash;prepare a repository to "
   1.631 +"work with MQ"
   1.632 +msgstr "<command role=\"hg-ext-mq\">qinit</command>&emdash;为使用 MQ 配置版本库"
   1.633 +
   1.634 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.635 +#: ../en/appB-mq-ref.xml:151
   1.636 +msgid ""
   1.637 +"The <command role=\"hg-ext-mq\">qinit</command> command prepares a repository "
   1.638 +"to work with MQ.  It creates a directory called <filename role=\"special\" "
   1.639 +"class=\"directory\">.hg/patches</filename>."
   1.640 +msgstr ""
   1.641 +
   1.642 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.643 +#: ../en/appB-mq-ref.xml:158
   1.644 +msgid ""
   1.645 +"<option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option>: Create <filename role="
   1.646 +"\"special\" class=\"directory\">.hg/patches</filename> as a repository in its "
   1.647 +"own right.  Also creates a <filename role=\"special\">.hgignore</filename> "
   1.648 +"file that will ignore the <filename role=\"special\">status</filename> file."
   1.649 +msgstr ""
   1.650 +
   1.651 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.652 +#: ../en/appB-mq-ref.xml:168
   1.653 +msgid ""
   1.654 +"When the <filename role=\"special\" class=\"directory\">.hg/patches</"
   1.655 +"filename> directory is a repository, the <command role=\"hg-ext-mq\">qimport</"
   1.656 +"command> and <command role=\"hg-ext-mq\">qnew</command> commands "
   1.657 +"automatically <command role=\"hg-cmd\">hg add</command> new patches."
   1.658 +msgstr ""
   1.659 +
   1.660 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.661 +#: ../en/appB-mq-ref.xml:177
   1.662 +msgid "<command role=\"hg-ext-mq\">qnew</command>&emdash;create a new patch"
   1.663 +msgstr "<command role=\"hg-ext-mq\">qnew</command>&emdash;创建新补丁"
   1.664 +
   1.665 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.666 +#: ../en/appB-mq-ref.xml:180
   1.667 +msgid ""
   1.668 +"The <command role=\"hg-ext-mq\">qnew</command> command creates a new patch.  "
   1.669 +"It takes one mandatory argument, the name to use for the patch file.  The "
   1.670 +"newly created patch is created empty by default.  It is added to the "
   1.671 +"<filename role=\"special\">series</filename> file after the current topmost "
   1.672 +"applied patch, and is immediately pushed on top of that patch."
   1.673 +msgstr ""
   1.674 +
   1.675 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.676 +#: ../en/appB-mq-ref.xml:188
   1.677 +msgid ""
   1.678 +"If <command role=\"hg-ext-mq\">qnew</command> finds modified files in the "
   1.679 +"working directory, it will refuse to create a new patch unless the <option "
   1.680 +"role=\"hg-ext-mq-cmd-qnew-opt\">-f</option> option is used (see below).  This "
   1.681 +"behaviour allows you to <command role=\"hg-ext-mq\">qrefresh</command> your "
   1.682 +"topmost applied patch before you apply a new patch on top of it."
   1.683 +msgstr ""
   1.684 +
   1.685 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.686 +#: ../en/appB-mq-ref.xml:198
   1.687 +msgid ""
   1.688 +"<option role=\"hg-ext-mq-cmd-qnew-opt\">-f</option>: Create a new patch if "
   1.689 +"the contents of the working directory are modified.  Any outstanding "
   1.690 +"modifications are added to the newly created patch, so after this command "
   1.691 +"completes, the working directory will no longer be modified."
   1.692 +msgstr ""
   1.693 +
   1.694 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.695 +#: ../en/appB-mq-ref.xml:205
   1.696 +msgid ""
   1.697 +"<option role=\"hg-ext-mq-cmd-qnew-opt\">-m</option>: Use the given text as "
   1.698 +"the commit message. This text will be stored at the beginning of the patch "
   1.699 +"file, before the patch data."
   1.700 +msgstr ""
   1.701 +
   1.702 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.703 +#: ../en/appB-mq-ref.xml:214
   1.704 +msgid ""
   1.705 +"<command role=\"hg-ext-mq\">qnext</command>&emdash;print the name of the next "
   1.706 +"patch"
   1.707 +msgstr "<command role=\"hg-ext-mq\">qnext</command>&emdash;显示下个补丁的名称"
   1.708 +
   1.709 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.710 +#: ../en/appB-mq-ref.xml:217
   1.711 +msgid ""
   1.712 +"The <command role=\"hg-ext-mq\">qnext</command> command prints the name name "
   1.713 +"of the next patch in the <filename role=\"special\">series</filename> file "
   1.714 +"after the topmost applied patch.  This patch will become the topmost applied "
   1.715 +"patch if you run <command role=\"hg-ext-mq\">qpush</command>."
   1.716 +msgstr ""
   1.717 +
   1.718 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.719 +#: ../en/appB-mq-ref.xml:226
   1.720 +msgid ""
   1.721 +"<command role=\"hg-ext-mq\">qpop</command>&emdash;pop patches off the stack"
   1.722 +msgstr "<command role=\"hg-ext-mq\">qpop</command>&emdash;删除堆栈顶部的补丁"
   1.723 +
   1.724 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.725 +#: ../en/appB-mq-ref.xml:229
   1.726 +msgid ""
   1.727 +"The <command role=\"hg-ext-mq\">qpop</command> command removes applied "
   1.728 +"patches from the top of the stack of applied patches.  By default, it removes "
   1.729 +"only one patch."
   1.730 +msgstr ""
   1.731 +
   1.732 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.733 +#: ../en/appB-mq-ref.xml:233
   1.734 +msgid ""
   1.735 +"This command removes the changesets that represent the popped patches from "
   1.736 +"the repository, and updates the working directory to undo the effects of the "
   1.737 +"patches."
   1.738 +msgstr ""
   1.739 +
   1.740 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.741 +#: ../en/appB-mq-ref.xml:237
   1.742 +msgid ""
   1.743 +"This command takes an optional argument, which it uses as the name or index "
   1.744 +"of the patch to pop to.  If given a name, it will pop patches until the named "
   1.745 +"patch is the topmost applied patch.  If given a number, <command role=\"hg-"
   1.746 +"ext-mq\">qpop</command> treats the number as an index into the entries in the "
   1.747 +"series file, counting from zero (empty lines and lines containing only "
   1.748 +"comments do not count).  It pops patches until the patch identified by the "
   1.749 +"given index is the topmost applied patch."
   1.750 +msgstr ""
   1.751 +
   1.752 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.753 +#: ../en/appB-mq-ref.xml:247
   1.754 +msgid ""
   1.755 +"The <command role=\"hg-ext-mq\">qpop</command> command does not read or write "
   1.756 +"patches or the <filename role=\"special\">series</filename> file.  It is thus "
   1.757 +"safe to <command role=\"hg-ext-mq\">qpop</command> a patch that you have "
   1.758 +"removed from the <filename role=\"special\">series</filename> file, or a "
   1.759 +"patch that you have renamed or deleted entirely.  In the latter two cases, "
   1.760 +"use the name of the patch as it was when you applied it."
   1.761 +msgstr ""
   1.762 +
   1.763 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.764 +#: ../en/appB-mq-ref.xml:256
   1.765 +msgid ""
   1.766 +"By default, the <command role=\"hg-ext-mq\">qpop</command> command will not "
   1.767 +"pop any patches if the working directory has been modified.  You can override "
   1.768 +"this behaviour using the <option role=\"hg-ext-mq-cmd-qpop-opt\">-f</option> "
   1.769 +"option, which reverts all modifications in the working directory."
   1.770 +msgstr ""
   1.771 +
   1.772 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.773 +#: ../en/appB-mq-ref.xml:265
   1.774 +msgid ""
   1.775 +"<option role=\"hg-ext-mq-cmd-qpop-opt\">-a</option>: Pop all applied "
   1.776 +"patches.  This returns the repository to its state before you applied any "
   1.777 +"patches."
   1.778 +msgstr ""
   1.779 +
   1.780 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.781 +#: ../en/appB-mq-ref.xml:270
   1.782 +msgid ""
   1.783 +"<option role=\"hg-ext-mq-cmd-qpop-opt\">-f</option>: Forcibly revert any "
   1.784 +"modifications to the working directory when popping."
   1.785 +msgstr ""
   1.786 +
   1.787 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.788 +#: ../en/appB-mq-ref.xml:275
   1.789 +msgid ""
   1.790 +"<option role=\"hg-ext-mq-cmd-qpop-opt\">-n</option>: Pop a patch from the "
   1.791 +"named queue."
   1.792 +msgstr ""
   1.793 +
   1.794 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.795 +#: ../en/appB-mq-ref.xml:280
   1.796 +msgid ""
   1.797 +"The <command role=\"hg-ext-mq\">qpop</command> command removes one line from "
   1.798 +"the end of the <filename role=\"special\">status</filename> file for each "
   1.799 +"patch that it pops."
   1.800 +msgstr ""
   1.801 +
   1.802 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.803 +#: ../en/appB-mq-ref.xml:287
   1.804 +msgid ""
   1.805 +"<command role=\"hg-ext-mq\">qprev</command>&emdash;print the name of the "
   1.806 +"previous patch"
   1.807 +msgstr "<command role=\"hg-ext-mq\">qprev</command>&emdash;显示上个补丁的名称"
   1.808 +
   1.809 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.810 +#: ../en/appB-mq-ref.xml:290
   1.811 +msgid ""
   1.812 +"The <command role=\"hg-ext-mq\">qprev</command> command prints the name of "
   1.813 +"the patch in the <filename role=\"special\">series</filename> file that comes "
   1.814 +"before the topmost applied patch. This will become the topmost applied patch "
   1.815 +"if you run <command role=\"hg-ext-mq\">qpop</command>."
   1.816 +msgstr ""
   1.817 +
   1.818 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.819 +#: ../en/appB-mq-ref.xml:299
   1.820 +msgid ""
   1.821 +"<command role=\"hg-ext-mq\">qpush</command>&emdash;push patches onto the stack"
   1.822 +msgstr "<command role=\"hg-ext-mq\">qpush</command>&emdash;增加补丁到堆栈"
   1.823 +
   1.824 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.825 +#: ../en/appB-mq-ref.xml:302
   1.826 +msgid ""
   1.827 +"The <command role=\"hg-ext-mq\">qpush</command> command adds patches onto the "
   1.828 +"applied stack.  By default, it adds only one patch."
   1.829 +msgstr ""
   1.830 +
   1.831 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.832 +#: ../en/appB-mq-ref.xml:306
   1.833 +msgid ""
   1.834 +"This command creates a new changeset to represent each applied patch, and "
   1.835 +"updates the working directory to apply the effects of the patches."
   1.836 +msgstr ""
   1.837 +
   1.838 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.839 +#: ../en/appB-mq-ref.xml:310
   1.840 +msgid "The default data used when creating a changeset are as follows:"
   1.841 +msgstr ""
   1.842 +
   1.843 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.844 +#: ../en/appB-mq-ref.xml:313
   1.845 +msgid ""
   1.846 +"The commit date and time zone are the current date and time zone.  Because "
   1.847 +"these data are used to compute the identity of a changeset, this means that "
   1.848 +"if you <command role=\"hg-ext-mq\">qpop</command> a patch and <command role="
   1.849 +"\"hg-ext-mq\">qpush</command> it again, the changeset that you push will have "
   1.850 +"a different identity than the changeset you popped."
   1.851 +msgstr ""
   1.852 +
   1.853 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.854 +#: ../en/appB-mq-ref.xml:321
   1.855 +msgid ""
   1.856 +"The author is the same as the default used by the <command role=\"hg-cmd\">hg "
   1.857 +"commit</command> command."
   1.858 +msgstr ""
   1.859 +
   1.860 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.861 +#: ../en/appB-mq-ref.xml:325
   1.862 +msgid ""
   1.863 +"The commit message is any text from the patch file that comes before the "
   1.864 +"first diff header.  If there is no such text, a default commit message is "
   1.865 +"used that identifies the name of the patch."
   1.866 +msgstr ""
   1.867 +
   1.868 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.869 +#: ../en/appB-mq-ref.xml:330
   1.870 +msgid ""
   1.871 +"If a patch contains a Mercurial patch header (XXX add link), the information "
   1.872 +"in the patch header overrides these defaults."
   1.873 +msgstr ""
   1.874 +
   1.875 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.876 +#: ../en/appB-mq-ref.xml:336
   1.877 +msgid ""
   1.878 +"<option role=\"hg-ext-mq-cmd-qpush-opt\">-a</option>: Push all unapplied "
   1.879 +"patches from the <filename role=\"special\">series</filename> file until "
   1.880 +"there are none left to push."
   1.881 +msgstr ""
   1.882 +
   1.883 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.884 +#: ../en/appB-mq-ref.xml:342
   1.885 +msgid ""
   1.886 +"<option role=\"hg-ext-mq-cmd-qpush-opt\">-l</option>: Add the name of the "
   1.887 +"patch to the end of the commit message."
   1.888 +msgstr ""
   1.889 +
   1.890 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.891 +#: ../en/appB-mq-ref.xml:346
   1.892 +msgid ""
   1.893 +"<option role=\"hg-ext-mq-cmd-qpush-opt\">-m</option>: If a patch fails to "
   1.894 +"apply cleanly, use the entry for the patch in another saved queue to compute "
   1.895 +"the parameters for a three-way merge, and perform a three-way merge using the "
   1.896 +"normal Mercurial merge machinery.  Use the resolution of the merge as the new "
   1.897 +"patch content."
   1.898 +msgstr ""
   1.899 +
   1.900 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.901 +#: ../en/appB-mq-ref.xml:354
   1.902 +msgid ""
   1.903 +"<option role=\"hg-ext-mq-cmd-qpush-opt\">-n</option>: Use the named queue if "
   1.904 +"merging while pushing."
   1.905 +msgstr ""
   1.906 +
   1.907 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.908 +#: ../en/appB-mq-ref.xml:359
   1.909 +msgid ""
   1.910 +"The <command role=\"hg-ext-mq\">qpush</command> command reads, but does not "
   1.911 +"modify, the <filename role=\"special\">series</filename> file.  It appends "
   1.912 +"one line to the <command role=\"hg-cmd\">hg status</command> file for each "
   1.913 +"patch that it pushes."
   1.914 +msgstr ""
   1.915 +
   1.916 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.917 +#: ../en/appB-mq-ref.xml:367
   1.918 +msgid ""
   1.919 +"<command role=\"hg-ext-mq\">qrefresh</command>&emdash;update the topmost "
   1.920 +"applied patch"
   1.921 +msgstr "<command role=\"hg-ext-mq\">qrefresh</command>&emdash;更新最新的补丁"
   1.922 +
   1.923 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.924 +#: ../en/appB-mq-ref.xml:371
   1.925 +msgid ""
   1.926 +"The <command role=\"hg-ext-mq\">qrefresh</command> command updates the "
   1.927 +"topmost applied patch.  It modifies the patch, removes the old changeset that "
   1.928 +"represented the patch, and creates a new changeset to represent the modified "
   1.929 +"patch."
   1.930 +msgstr ""
   1.931 +
   1.932 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.933 +#: ../en/appB-mq-ref.xml:377
   1.934 +msgid ""
   1.935 +"The <command role=\"hg-ext-mq\">qrefresh</command> command looks for the "
   1.936 +"following modifications:"
   1.937 +msgstr ""
   1.938 +
   1.939 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.940 +#: ../en/appB-mq-ref.xml:380
   1.941 +msgid ""
   1.942 +"Changes to the commit message, i.e. the text before the first diff header in "
   1.943 +"the patch file, are reflected in the new changeset that represents the patch."
   1.944 +msgstr ""
   1.945 +
   1.946 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.947 +#: ../en/appB-mq-ref.xml:385
   1.948 +msgid ""
   1.949 +"Modifications to tracked files in the working directory are added to the "
   1.950 +"patch."
   1.951 +msgstr ""
   1.952 +
   1.953 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.954 +#: ../en/appB-mq-ref.xml:388
   1.955 +msgid ""
   1.956 +"Changes to the files tracked using <command role=\"hg-cmd\">hg add</command>, "
   1.957 +"<command role=\"hg-cmd\">hg copy</command>, <command role=\"hg-cmd\">hg "
   1.958 +"remove</command>, or <command role=\"hg-cmd\">hg rename</command>.  Added "
   1.959 +"files and copy and rename destinations are added to the patch, while removed "
   1.960 +"files and rename sources are removed."
   1.961 +msgstr ""
   1.962 +
   1.963 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.964 +#: ../en/appB-mq-ref.xml:397
   1.965 +msgid ""
   1.966 +"Even if <command role=\"hg-ext-mq\">qrefresh</command> detects no changes, it "
   1.967 +"still recreates the changeset that represents the patch.  This causes the "
   1.968 +"identity of the changeset to differ from the previous changeset that "
   1.969 +"identified the patch."
   1.970 +msgstr ""
   1.971 +
   1.972 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.973 +#: ../en/appB-mq-ref.xml:405
   1.974 +msgid ""
   1.975 +"<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-e</option>: Modify the commit "
   1.976 +"and patch description, using the preferred text editor."
   1.977 +msgstr ""
   1.978 +
   1.979 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.980 +#: ../en/appB-mq-ref.xml:410
   1.981 +msgid ""
   1.982 +"<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-m</option>: Modify the commit "
   1.983 +"message and patch description, using the given text."
   1.984 +msgstr ""
   1.985 +
   1.986 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
   1.987 +#: ../en/appB-mq-ref.xml:415
   1.988 +msgid ""
   1.989 +"<option role=\"hg-ext-mq-cmd-qrefresh-opt\">-l</option>: Modify the commit "
   1.990 +"message and patch description, using text from the given file."
   1.991 +msgstr ""
   1.992 +
   1.993 +#. type: Content of: <book><appendix><sect1><sect2><title>
   1.994 +#: ../en/appB-mq-ref.xml:423
   1.995 +msgid "<command role=\"hg-ext-mq\">qrename</command>&emdash;rename a patch"
   1.996 +msgstr "<command role=\"hg-ext-mq\">qrename</command>&emdash;改名补丁"
   1.997 +
   1.998 +#. type: Content of: <book><appendix><sect1><sect2><para>
   1.999 +#: ../en/appB-mq-ref.xml:426
  1.1000 +msgid ""
  1.1001 +"The <command role=\"hg-ext-mq\">qrename</command> command renames a patch, "
  1.1002 +"and changes the entry for the patch in the <filename role=\"special\">series</"
  1.1003 +"filename> file."
  1.1004 +msgstr ""
  1.1005 +
  1.1006 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1007 +#: ../en/appB-mq-ref.xml:430
  1.1008 +msgid ""
  1.1009 +"With a single argument, <command role=\"hg-ext-mq\">qrename</command> renames "
  1.1010 +"the topmost applied patch.  With two arguments, it renames its first argument "
  1.1011 +"to its second."
  1.1012 +msgstr ""
  1.1013 +
  1.1014 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1015 +#: ../en/appB-mq-ref.xml:437
  1.1016 +msgid ""
  1.1017 +"<command role=\"hg-ext-mq\">qrestore</command>&emdash;restore saved queue "
  1.1018 +"state"
  1.1019 +msgstr "<command role=\"hg-ext-mq\">qrestore</command>&emdash;恢复保存的队列"
  1.1020 +
  1.1021 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1022 +#: ../en/appB-mq-ref.xml:441
  1.1023 +msgid "XXX No idea what this does."
  1.1024 +msgstr ""
  1.1025 +
  1.1026 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1027 +#: ../en/appB-mq-ref.xml:445
  1.1028 +msgid ""
  1.1029 +"<command role=\"hg-ext-mq\">qsave</command>&emdash;save current queue state"
  1.1030 +msgstr "<command role=\"hg-ext-mq\">qsave</command>&emdash;保存当前的队列状态"
  1.1031 +
  1.1032 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1033 +#: ../en/appB-mq-ref.xml:448
  1.1034 +msgid "XXX Likewise."
  1.1035 +msgstr ""
  1.1036 +
  1.1037 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1038 +#: ../en/appB-mq-ref.xml:452
  1.1039 +msgid ""
  1.1040 +"<command role=\"hg-ext-mq\">qseries</command>&emdash;print the entire patch "
  1.1041 +"series"
  1.1042 +msgstr "<command role=\"hg-ext-mq\">qseries</command>&emdash;显示补丁序列"
  1.1043 +
  1.1044 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1045 +#: ../en/appB-mq-ref.xml:455
  1.1046 +msgid ""
  1.1047 +"The <command role=\"hg-ext-mq\">qseries</command> command prints the entire "
  1.1048 +"patch series from the <filename role=\"special\">series</filename> file.  It "
  1.1049 +"prints only patch names, not empty lines or comments.  It prints in order "
  1.1050 +"from first to be applied to last."
  1.1051 +msgstr ""
  1.1052 +
  1.1053 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1054 +#: ../en/appB-mq-ref.xml:463
  1.1055 +msgid ""
  1.1056 +"<command role=\"hg-ext-mq\">qtop</command>&emdash;print the name of the "
  1.1057 +"current patch"
  1.1058 +msgstr "<command role=\"hg-ext-mq\">qtop</command>&emdash;显示当前补丁的名称"
  1.1059 +
  1.1060 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1061 +#: ../en/appB-mq-ref.xml:466
  1.1062 +msgid ""
  1.1063 +"The <command role=\"hg-ext-mq\">qtop</command> prints the name of the topmost "
  1.1064 +"currently applied patch."
  1.1065 +msgstr ""
  1.1066 +
  1.1067 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1068 +#: ../en/appB-mq-ref.xml:471
  1.1069 +msgid ""
  1.1070 +"<command role=\"hg-ext-mq\">qunapplied</command>&emdash;print patches not yet "
  1.1071 +"applied"
  1.1072 +msgstr ""
  1.1073 +"<command role=\"hg-ext-mq\">qunapplied</command>&emdash;显示尚未应用的补丁"
  1.1074 +
  1.1075 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1076 +#: ../en/appB-mq-ref.xml:475
  1.1077 +msgid ""
  1.1078 +"The <command role=\"hg-ext-mq\">qunapplied</command> command prints the names "
  1.1079 +"of patches from the <filename role=\"special\">series</filename> file that "
  1.1080 +"are not yet applied.  It prints them in order from the next patch that will "
  1.1081 +"be pushed to the last."
  1.1082 +msgstr ""
  1.1083 +
  1.1084 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1085 +#: ../en/appB-mq-ref.xml:483
  1.1086 +msgid ""
  1.1087 +"<command role=\"hg-cmd\">hg strip</command>&emdash;remove a revision and "
  1.1088 +"descendants"
  1.1089 +msgstr "<command role=\"hg-cmd\">hg strip</command>&emdash;删除一个版本及其后继"
  1.1090 +
  1.1091 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1092 +#: ../en/appB-mq-ref.xml:486
  1.1093 +msgid ""
  1.1094 +"The <command role=\"hg-cmd\">hg strip</command> command removes a revision, "
  1.1095 +"and all of its descendants, from the repository.  It undoes the effects of "
  1.1096 +"the removed revisions from the repository, and updates the working directory "
  1.1097 +"to the first parent of the removed revision."
  1.1098 +msgstr ""
  1.1099 +
  1.1100 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1101 +#: ../en/appB-mq-ref.xml:492
  1.1102 +msgid ""
  1.1103 +"The <command role=\"hg-cmd\">hg strip</command> command saves a backup of the "
  1.1104 +"removed changesets in a bundle, so that they can be reapplied if removed in "
  1.1105 +"error."
  1.1106 +msgstr ""
  1.1107 +
  1.1108 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
  1.1109 +#: ../en/appB-mq-ref.xml:498
  1.1110 +msgid ""
  1.1111 +"<option role=\"hg-opt-strip\">-b</option>: Save unrelated changesets that are "
  1.1112 +"intermixed with the stripped changesets in the backup bundle."
  1.1113 +msgstr ""
  1.1114 +
  1.1115 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
  1.1116 +#: ../en/appB-mq-ref.xml:502
  1.1117 +msgid ""
  1.1118 +"<option role=\"hg-opt-strip\">-f</option>: If a branch has multiple heads, "
  1.1119 +"remove all heads. XXX This should be renamed, and use <literal>-f</literal> "
  1.1120 +"to strip revs when there are pending changes."
  1.1121 +msgstr ""
  1.1122 +
  1.1123 +#. type: Content of: <book><appendix><sect1><sect2><itemizedlist><listitem><para>
  1.1124 +#: ../en/appB-mq-ref.xml:507
  1.1125 +msgid "<option role=\"hg-opt-strip\">-n</option>: Do not save a backup bundle."
  1.1126 +msgstr ""
  1.1127 +
  1.1128 +#. type: Content of: <book><appendix><sect1><title>
  1.1129 +#: ../en/appB-mq-ref.xml:514
  1.1130 +msgid "MQ file reference"
  1.1131 +msgstr "MQ 文件参考"
  1.1132 +
  1.1133 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1134 +#: ../en/appB-mq-ref.xml:517
  1.1135 +msgid "The <filename role=\"special\">series</filename> file"
  1.1136 +msgstr "<filename role=\"special\">序列</filename>文件"
  1.1137 +
  1.1138 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1139 +#: ../en/appB-mq-ref.xml:520
  1.1140 +msgid ""
  1.1141 +"The <filename role=\"special\">series</filename> file contains a list of the "
  1.1142 +"names of all patches that MQ can apply.  It is represented as a list of "
  1.1143 +"names, with one name saved per line.  Leading and trailing white space in "
  1.1144 +"each line are ignored."
  1.1145 +msgstr ""
  1.1146 +
  1.1147 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1148 +#: ../en/appB-mq-ref.xml:526
  1.1149 +msgid ""
  1.1150 +"Lines may contain comments.  A comment begins with the <quote><literal>#</"
  1.1151 +"literal></quote> character, and extends to the end of the line.  Empty lines, "
  1.1152 +"and lines that contain only comments, are ignored."
  1.1153 +msgstr ""
  1.1154 +
  1.1155 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1156 +#: ../en/appB-mq-ref.xml:531
  1.1157 +msgid ""
  1.1158 +"You will often need to edit the <filename role=\"special\">series</filename> "
  1.1159 +"file by hand, hence the support for comments and empty lines noted above.  "
  1.1160 +"For example, you can comment out a patch temporarily, and <command role=\"hg-"
  1.1161 +"ext-mq\">qpush</command> will skip over that patch when applying patches.  "
  1.1162 +"You can also change the order in which patches are applied by reordering "
  1.1163 +"their entries in the <filename role=\"special\">series</filename> file."
  1.1164 +msgstr ""
  1.1165 +
  1.1166 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1167 +#: ../en/appB-mq-ref.xml:540
  1.1168 +msgid ""
  1.1169 +"Placing the <filename role=\"special\">series</filename> file under revision "
  1.1170 +"control is also supported; it is a good idea to place all of the patches that "
  1.1171 +"it refers to under revision control, as well.  If you create a patch "
  1.1172 +"directory using the <option role=\"hg-ext-mq-cmd-qinit-opt\">-c</option> "
  1.1173 +"option to <command role=\"hg-ext-mq\">qinit</command>, this will be done for "
  1.1174 +"you automatically."
  1.1175 +msgstr ""
  1.1176 +
  1.1177 +#. type: Content of: <book><appendix><sect1><sect2><title>
  1.1178 +#: ../en/appB-mq-ref.xml:550
  1.1179 +msgid "The <filename role=\"special\">status</filename> file"
  1.1180 +msgstr "<filename role=\"special\">状态</filename>文件"
  1.1181 +
  1.1182 +#. type: Content of: <book><appendix><sect1><sect2><para>
  1.1183 +#: ../en/appB-mq-ref.xml:553
  1.1184 +msgid ""
  1.1185 +"The <filename role=\"special\">status</filename> file contains the names and "
  1.1186 +"changeset hashes of all patches that MQ currently has applied.  Unlike the "
  1.1187 +"<filename role=\"special\">series</filename> file, this file is not intended "
  1.1188 +"for editing.  You should not place this file under revision control, or "
  1.1189 +"modify it in any way.  It is used by MQ strictly for internal book-keeping."
  1.1190 +msgstr ""
  1.1191 +
  1.1192 +#. type: Content of: <book><appendix><title>
  1.1193 +#: ../en/appC-srcinstall.xml:5
  1.1194 +msgid "Installing Mercurial from source"
  1.1195 +msgstr "从源代码安装 Mercurial"
  1.1196 +
  1.1197 +#. type: Content of: <book><appendix><sect1><title>
  1.1198 +#: ../en/appC-srcinstall.xml:8
  1.1199 +msgid "On a Unix-like system"
  1.1200 +msgstr "类 Unix 系统"
  1.1201 +
  1.1202 +#. type: Content of: <book><appendix><sect1><para>
  1.1203 +#: ../en/appC-srcinstall.xml:10
  1.1204 +msgid ""
  1.1205 +"If you are using a Unix-like system that has a sufficiently recent version of "
  1.1206 +"Python (2.3 or newer) available, it is easy to install Mercurial from source."
  1.1207 +msgstr ""
  1.1208 +
  1.1209 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1210 +#: ../en/appC-srcinstall.xml:14
  1.1211 +msgid ""
  1.1212 +"Download a recent source tarball from <ulink url=\"http://www.selenic.com/"
  1.1213 +"mercurial/download\">http://www.selenic.com/mercurial/download</ulink>."
  1.1214 +msgstr ""
  1.1215 +
  1.1216 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1217 +#: ../en/appC-srcinstall.xml:17
  1.1218 +msgid "Unpack the tarball:"
  1.1219 +msgstr ""
  1.1220 +
  1.1221 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1222 +#: ../en/appC-srcinstall.xml:20
  1.1223 +msgid ""
  1.1224 +"Go into the source directory and run the installer script.  This will build "
  1.1225 +"Mercurial and install it in your home directory."
  1.1226 +msgstr ""
  1.1227 +
  1.1228 +#. type: Content of: <book><appendix><sect1><para>
  1.1229 +#: ../en/appC-srcinstall.xml:27
  1.1230 +msgid ""
  1.1231 +"Once the install finishes, Mercurial will be in the <literal>bin</literal> "
  1.1232 +"subdirectory of your home directory.  Don't forget to make sure that this "
  1.1233 +"directory is present in your shell's search path."
  1.1234 +msgstr ""
  1.1235 +
  1.1236 +#. type: Content of: <book><appendix><sect1><para>
  1.1237 +#: ../en/appC-srcinstall.xml:32
  1.1238 +msgid ""
  1.1239 +"You will probably need to set the <envar>PYTHONPATH</envar> environment "
  1.1240 +"variable so that the Mercurial executable can find the rest of the Mercurial "
  1.1241 +"packages.  For example, on my laptop, I have set it to <literal>/home/bos/lib/"
  1.1242 +"python</literal>.  The exact path that you will need to use depends on how "
  1.1243 +"Python was built for your system, but should be easy to figure out.  If "
  1.1244 +"you're uncertain, look through the output of the installer script above, and "
  1.1245 +"see where the contents of the <literal>mercurial</literal> directory were "
  1.1246 +"installed to."
  1.1247 +msgstr ""
  1.1248 +
  1.1249 +#. type: Content of: <book><appendix><sect1><title>
  1.1250 +#: ../en/appC-srcinstall.xml:44
  1.1251 +msgid "On Windows"
  1.1252 +msgstr "Windows 系统"
  1.1253 +
  1.1254 +#. type: Content of: <book><appendix><sect1><para>
  1.1255 +#: ../en/appC-srcinstall.xml:46
  1.1256 +msgid ""
  1.1257 +"Building and installing Mercurial on Windows requires a variety of tools, a "
  1.1258 +"fair amount of technical knowledge, and considerable patience.  I very much "
  1.1259 +"<emphasis>do not recommend</emphasis> this route if you are a <quote>casual "
  1.1260 +"user</quote>.  Unless you intend to hack on Mercurial, I strongly suggest "
  1.1261 +"that you use a binary package instead."
  1.1262 +msgstr ""
  1.1263 +
  1.1264 +#. type: Content of: <book><appendix><sect1><para>
  1.1265 +#: ../en/appC-srcinstall.xml:53
  1.1266 +msgid ""
  1.1267 +"If you are intent on building Mercurial from source on Windows, follow the "
  1.1268 +"<quote>hard way</quote> directions on the Mercurial wiki at <ulink url="
  1.1269 +"\"http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall\">http://www."
  1.1270 +"selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, and expect the "
  1.1271 +"process to involve a lot of fiddly work."
  1.1272 +msgstr ""
  1.1273 +
  1.1274 +#. type: Content of: <book><appendix><title>
  1.1275 +#: ../en/appD-license.xml:5
  1.1276 +msgid "Open Publication License"
  1.1277 +msgstr ""
  1.1278 +
  1.1279 +#. type: Content of: <book><appendix><para>
  1.1280 +#: ../en/appD-license.xml:7
  1.1281 +msgid "Version 1.0, 8 June 1999"
  1.1282 +msgstr ""
  1.1283 +
  1.1284 +#. type: Content of: <book><appendix><sect1><title>
  1.1285 +#: ../en/appD-license.xml:10
  1.1286 +msgid "Requirements on both unmodified and modified versions"
  1.1287 +msgstr ""
  1.1288 +
  1.1289 +#. type: Content of: <book><appendix><sect1><para>
  1.1290 +#: ../en/appD-license.xml:13
  1.1291 +msgid ""
  1.1292 +"The Open Publication works may be reproduced and distributed in whole or in "
  1.1293 +"part, in any medium physical or electronic, provided that the terms of this "
  1.1294 +"license are adhered to, and that this license or an incorporation of it by "
  1.1295 +"reference (with any options elected by the author(s) and/or publisher) is "
  1.1296 +"displayed in the reproduction."
  1.1297 +msgstr ""
  1.1298 +
  1.1299 +#. type: Content of: <book><appendix><sect1><para>
  1.1300 +#: ../en/appD-license.xml:20
  1.1301 +msgid "Proper form for an incorporation by reference is as follows:"
  1.1302 +msgstr ""
  1.1303 +
  1.1304 +#. type: Content of: <book><appendix><sect1><blockquote><para>
  1.1305 +#: ../en/appD-license.xml:24
  1.1306 +msgid ""
  1.1307 +"Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or "
  1.1308 +"designee</emphasis>. This material may be distributed only subject to the "
  1.1309 +"terms and conditions set forth in the Open Publication License, v<emphasis>x."
  1.1310 +"y</emphasis> or later (the latest version is presently available at <ulink "
  1.1311 +"url=\"http://www.opencontent.org/openpub/\">http://www.opencontent.org/"
  1.1312 +"openpub/</ulink>)."
  1.1313 +msgstr ""
  1.1314 +
  1.1315 +#. type: Content of: <book><appendix><sect1><para>
  1.1316 +#: ../en/appD-license.xml:33
  1.1317 +msgid ""
  1.1318 +"The reference must be immediately followed with any options elected by the "
  1.1319 +"author(s) and/or publisher of the document (see section <xref linkend=\"sec."
  1.1320 +"opl.options\"/>)."
  1.1321 +msgstr ""
  1.1322 +
  1.1323 +#. type: Content of: <book><appendix><sect1><para>
  1.1324 +#: ../en/appD-license.xml:37
  1.1325 +msgid ""
  1.1326 +"Commercial redistribution of Open Publication-licensed material is permitted."
  1.1327 +msgstr ""
  1.1328 +
  1.1329 +#. type: Content of: <book><appendix><sect1><para>
  1.1330 +#: ../en/appD-license.xml:40
  1.1331 +msgid ""
  1.1332 +"Any publication in standard (paper) book form shall require the citation of "
  1.1333 +"the original publisher and author. The publisher and author's names shall "
  1.1334 +"appear on all outer surfaces of the book. On all outer surfaces of the book "
  1.1335 +"the original publisher's name shall be as large as the title of the work and "
  1.1336 +"cited as possessive with respect to the title."
  1.1337 +msgstr ""
  1.1338 +
  1.1339 +#. type: Content of: <book><appendix><sect1><title>
  1.1340 +#: ../en/appD-license.xml:49
  1.1341 +msgid "Copyright"
  1.1342 +msgstr ""
  1.1343 +
  1.1344 +#. type: Content of: <book><appendix><sect1><para>
  1.1345 +#: ../en/appD-license.xml:51
  1.1346 +msgid ""
  1.1347 +"The copyright to each Open Publication is owned by its author(s) or designee."
  1.1348 +msgstr ""
  1.1349 +
  1.1350 +#. type: Content of: <book><appendix><sect1><title>
  1.1351 +#: ../en/appD-license.xml:56
  1.1352 +msgid "Scope of license"
  1.1353 +msgstr ""
  1.1354 +
  1.1355 +#. type: Content of: <book><appendix><sect1><para>
  1.1356 +#: ../en/appD-license.xml:58
  1.1357 +msgid ""
  1.1358 +"The following license terms apply to all Open Publication works, unless "
  1.1359 +"otherwise explicitly stated in the document."
  1.1360 +msgstr ""
  1.1361 +
  1.1362 +#. type: Content of: <book><appendix><sect1><para>
  1.1363 +#: ../en/appD-license.xml:62
  1.1364 +msgid ""
  1.1365 +"Mere aggregation of Open Publication works or a portion of an Open "
  1.1366 +"Publication work with other works or programs on the same media shall not "
  1.1367 +"cause this license to apply to those other works. The aggregate work shall "
  1.1368 +"contain a notice specifying the inclusion of the Open Publication material "
  1.1369 +"and appropriate copyright notice."
  1.1370 +msgstr ""
  1.1371 +
  1.1372 +#. type: Content of: <book><appendix><sect1><para>
  1.1373 +#: ../en/appD-license.xml:69
  1.1374 +msgid ""
  1.1375 +"<emphasis role=\"bold\">Severability</emphasis>. If any part of this license "
  1.1376 +"is found to be unenforceable in any jurisdiction, the remaining portions of "
  1.1377 +"the license remain in force."
  1.1378 +msgstr ""
  1.1379 +
  1.1380 +#. type: Content of: <book><appendix><sect1><para>
  1.1381 +#: ../en/appD-license.xml:74
  1.1382 +msgid ""
  1.1383 +"<emphasis role=\"bold\">No warranty</emphasis>. Open Publication works are "
  1.1384 +"licensed and provided <quote>as is</quote> without warranty of any kind, "
  1.1385 +"express or implied, including, but not limited to, the implied warranties of "
  1.1386 +"merchantability and fitness for a particular purpose or a warranty of non-"
  1.1387 +"infringement."
  1.1388 +msgstr ""
  1.1389 +
  1.1390 +#. type: Content of: <book><appendix><sect1><title>
  1.1391 +#: ../en/appD-license.xml:83
  1.1392 +msgid "Requirements on modified works"
  1.1393 +msgstr ""
  1.1394 +
  1.1395 +#. type: Content of: <book><appendix><sect1><para>
  1.1396 +#: ../en/appD-license.xml:85
  1.1397 +msgid ""
  1.1398 +"All modified versions of documents covered by this license, including "
  1.1399 +"translations, anthologies, compilations and partial documents, must meet the "
  1.1400 +"following requirements:"
  1.1401 +msgstr ""
  1.1402 +
  1.1403 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1404 +#: ../en/appD-license.xml:90
  1.1405 +msgid "The modified version must be labeled as such."
  1.1406 +msgstr ""
  1.1407 +
  1.1408 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1409 +#: ../en/appD-license.xml:93
  1.1410 +msgid ""
  1.1411 +"The person making the modifications must be identified and the modifications "
  1.1412 +"dated."
  1.1413 +msgstr ""
  1.1414 +
  1.1415 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1416 +#: ../en/appD-license.xml:96
  1.1417 +msgid ""
  1.1418 +"Acknowledgement of the original author and publisher if applicable must be "
  1.1419 +"retained according to normal academic citation practices."
  1.1420 +msgstr ""
  1.1421 +
  1.1422 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1423 +#: ../en/appD-license.xml:100
  1.1424 +msgid "The location of the original unmodified document must be identified."
  1.1425 +msgstr ""
  1.1426 +
  1.1427 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1428 +#: ../en/appD-license.xml:103
  1.1429 +msgid ""
  1.1430 +"The original author's (or authors') name(s) may not be used to assert or "
  1.1431 +"imply endorsement of the resulting document without the original author's (or "
  1.1432 +"authors')  permission."
  1.1433 +msgstr ""
  1.1434 +
  1.1435 +#. type: Content of: <book><appendix><sect1><title>
  1.1436 +#: ../en/appD-license.xml:111
  1.1437 +msgid "Good-practice recommendations"
  1.1438 +msgstr ""
  1.1439 +
  1.1440 +#. type: Content of: <book><appendix><sect1><para>
  1.1441 +#: ../en/appD-license.xml:113
  1.1442 +msgid ""
  1.1443 +"In addition to the requirements of this license, it is requested from and "
  1.1444 +"strongly recommended of redistributors that:"
  1.1445 +msgstr ""
  1.1446 +
  1.1447 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1448 +#: ../en/appD-license.xml:118
  1.1449 +msgid ""
  1.1450 +"If you are distributing Open Publication works on hardcopy or CD-ROM, you "
  1.1451 +"provide email notification to the authors of your intent to redistribute at "
  1.1452 +"least thirty days before your manuscript or media freeze, to give the authors "
  1.1453 +"time to provide updated documents. This notification should describe "
  1.1454 +"modifications, if any, made to the document."
  1.1455 +msgstr ""
  1.1456 +
  1.1457 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1458 +#: ../en/appD-license.xml:125
  1.1459 +msgid ""
  1.1460 +"All substantive modifications (including deletions) be either clearly marked "
  1.1461 +"up in the document or else described in an attachment to the document."
  1.1462 +msgstr ""
  1.1463 +
  1.1464 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1465 +#: ../en/appD-license.xml:129
  1.1466 +msgid ""
  1.1467 +"Finally, while it is not mandatory under this license, it is considered good "
  1.1468 +"form to offer a free copy of any hardcopy and CD-ROM expression of an Open "
  1.1469 +"Publication-licensed work to its author(s)."
  1.1470 +msgstr ""
  1.1471 +
  1.1472 +#. type: Content of: <book><appendix><sect1><title>
  1.1473 +#: ../en/appD-license.xml:137
  1.1474 +msgid "License options"
  1.1475 +msgstr ""
  1.1476 +
  1.1477 +#. type: Content of: <book><appendix><sect1><para>
  1.1478 +#: ../en/appD-license.xml:139
  1.1479 +msgid ""
  1.1480 +"The author(s) and/or publisher of an Open Publication-licensed document may "
  1.1481 +"elect certain options by appending language to the reference to or copy of "
  1.1482 +"the license.  These options are considered part of the license instance and "
  1.1483 +"must be included with the license (or its incorporation by reference) in "
  1.1484 +"derived works."
  1.1485 +msgstr ""
  1.1486 +
  1.1487 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1488 +#: ../en/appD-license.xml:147
  1.1489 +msgid ""
  1.1490 +"To prohibit distribution of substantively modified versions without the "
  1.1491 +"explicit permission of the author(s). <quote>Substantive modification</quote> "
  1.1492 +"is defined as a change to the semantic content of the document, and excludes "
  1.1493 +"mere changes in format or typographical corrections."
  1.1494 +msgstr ""
  1.1495 +
  1.1496 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1497 +#: ../en/appD-license.xml:154
  1.1498 +msgid ""
  1.1499 +"To accomplish this, add the phrase <quote>Distribution of substantively "
  1.1500 +"modified versions of this document is prohibited without the explicit "
  1.1501 +"permission of the copyright holder.</quote> to the license reference or copy."
  1.1502 +msgstr ""
  1.1503 +
  1.1504 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1505 +#: ../en/appD-license.xml:160
  1.1506 +msgid ""
  1.1507 +"To prohibit any publication of this work or derivative works in whole or in "
  1.1508 +"part in standard (paper)  book form for commercial purposes is prohibited "
  1.1509 +"unless prior permission is obtained from the copyright holder."
  1.1510 +msgstr ""
  1.1511 +
  1.1512 +#. type: Content of: <book><appendix><sect1><orderedlist><listitem><para>
  1.1513 +#: ../en/appD-license.xml:165
  1.1514 +msgid ""
  1.1515 +"To accomplish this, add the phrase <quote>Distribution of the work or "
  1.1516 +"derivative of the work in any standard (paper) book form is prohibited unless "
  1.1517 +"prior permission is obtained from the copyright holder.</quote> to the "
  1.1518 +"license reference or copy."
  1.1519 +msgstr ""
  1.1520 +
  1.1521 +#. type: Content of: <book><chapter><title>
  1.1522 +#: ../en/ch01-intro.xml:5
  1.1523 +msgid "Introduction"
  1.1524 +msgstr "简介"
  1.1525 +
  1.1526 +#. type: Content of: <book><chapter><sect1><title>
  1.1527 +#: ../en/ch01-intro.xml:8
  1.1528 +msgid "About revision control"
  1.1529 +msgstr "关于版本控制"
  1.1530 +
  1.1531 +#. type: Content of: <book><chapter><sect1><para>
  1.1532 +#: ../en/ch01-intro.xml:10
  1.1533 +msgid ""
  1.1534 +"Revision control is the process of managing multiple versions of a piece of "
  1.1535 +"information.  In its simplest form, this is something that many people do by "
  1.1536 +"hand: every time you modify a file, save it under a new name that contains a "
  1.1537 +"number, each one higher than the number of the preceding version."
  1.1538 +msgstr ""
  1.1539 +
  1.1540 +#. type: Content of: <book><chapter><sect1><para>
  1.1541 +#: ../en/ch01-intro.xml:16
  1.1542 +msgid ""
  1.1543 +"Manually managing multiple versions of even a single file is an error-prone "
  1.1544 +"task, though, so software tools to help automate this process have long been "
  1.1545 +"available.  The earliest automated revision control tools were intended to "
  1.1546 +"help a single user to manage revisions of a single file.  Over the past few "
  1.1547 +"decades, the scope of revision control tools has expanded greatly; they now "
  1.1548 +"manage multiple files, and help multiple people to work together.  The best "
  1.1549 +"modern revision control tools have no problem coping with thousands of people "
  1.1550 +"working together on projects that consist of hundreds of thousands of files."
  1.1551 +msgstr ""
  1.1552 +
  1.1553 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.1554 +#: ../en/ch01-intro.xml:28
  1.1555 +msgid "Why use revision control?"
  1.1556 +msgstr "为什么使用版本控制?"
  1.1557 +
  1.1558 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1559 +#: ../en/ch01-intro.xml:30
  1.1560 +msgid ""
  1.1561 +"There are a number of reasons why you or your team might want to use an "
  1.1562 +"automated revision control tool for a project."
  1.1563 +msgstr ""
  1.1564 +
  1.1565 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1566 +#: ../en/ch01-intro.xml:34
  1.1567 +msgid ""
  1.1568 +"It will track the history and evolution of your project, so you don't have "
  1.1569 +"to.  For every change, you'll have a log of <emphasis>who</emphasis> made it; "
  1.1570 +"<emphasis>why</emphasis> they made it; <emphasis>when</emphasis> they made "
  1.1571 +"it; and <emphasis>what</emphasis> the change was."
  1.1572 +msgstr ""
  1.1573 +
  1.1574 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1575 +#: ../en/ch01-intro.xml:41
  1.1576 +msgid ""
  1.1577 +"When you're working with other people, revision control software makes it "
  1.1578 +"easier for you to collaborate.  For example, when people more or less "
  1.1579 +"simultaneously make potentially incompatible changes, the software will help "
  1.1580 +"you to identify and resolve those conflicts."
  1.1581 +msgstr ""
  1.1582 +
  1.1583 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1584 +#: ../en/ch01-intro.xml:47
  1.1585 +msgid ""
  1.1586 +"It can help you to recover from mistakes.  If you make a change that later "
  1.1587 +"turns out to be in error, you can revert to an earlier version of one or more "
  1.1588 +"files.  In fact, a <emphasis>really</emphasis> good revision control tool "
  1.1589 +"will even help you to efficiently figure out exactly when a problem was "
  1.1590 +"introduced (see section <xref linkend=\"sec.undo.bisect\"/> for details)."
  1.1591 +msgstr ""
  1.1592 +
  1.1593 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1594 +#: ../en/ch01-intro.xml:54
  1.1595 +msgid ""
  1.1596 +"It will help you to work simultaneously on, and manage the drift between, "
  1.1597 +"multiple versions of your project."
  1.1598 +msgstr ""
  1.1599 +
  1.1600 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1601 +#: ../en/ch01-intro.xml:57
  1.1602 +msgid ""
  1.1603 +"Most of these reasons are equally valid---at least in theory---whether you're "
  1.1604 +"working on a project by yourself, or with a hundred other people."
  1.1605 +msgstr ""
  1.1606 +
  1.1607 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1608 +#: ../en/ch01-intro.xml:61
  1.1609 +msgid ""
  1.1610 +"A key question about the practicality of revision control at these two "
  1.1611 +"different scales (<quote>lone hacker</quote> and <quote>huge team</quote>) is "
  1.1612 +"how its <emphasis>benefits</emphasis> compare to its <emphasis>costs</"
  1.1613 +"emphasis>.  A revision control tool that's difficult to understand or use is "
  1.1614 +"going to impose a high cost."
  1.1615 +msgstr ""
  1.1616 +
  1.1617 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1618 +#: ../en/ch01-intro.xml:69
  1.1619 +msgid ""
  1.1620 +"A five-hundred-person project is likely to collapse under its own weight "
  1.1621 +"almost immediately without a revision control tool and process. In this case, "
  1.1622 +"the cost of using revision control might hardly seem worth considering, since "
  1.1623 +"<emphasis>without</emphasis> it, failure is almost guaranteed."
  1.1624 +msgstr ""
  1.1625 +
  1.1626 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1627 +#: ../en/ch01-intro.xml:76
  1.1628 +msgid ""
  1.1629 +"On the other hand, a one-person <quote>quick hack</quote> might seem like a "
  1.1630 +"poor place to use a revision control tool, because surely the cost of using "
  1.1631 +"one must be close to the overall cost of the project.  Right?"
  1.1632 +msgstr ""
  1.1633 +
  1.1634 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1635 +#: ../en/ch01-intro.xml:81
  1.1636 +msgid ""
  1.1637 +"Mercurial uniquely supports <emphasis>both</emphasis> of these scales of "
  1.1638 +"development.  You can learn the basics in just a few minutes, and due to its "
  1.1639 +"low overhead, you can apply revision control to the smallest of projects with "
  1.1640 +"ease.  Its simplicity means you won't have a lot of abstruse concepts or "
  1.1641 +"command sequences competing for mental space with whatever you're "
  1.1642 +"<emphasis>really</emphasis> trying to do.  At the same time, Mercurial's high "
  1.1643 +"performance and peer-to-peer nature let you scale painlessly to handle large "
  1.1644 +"projects."
  1.1645 +msgstr ""
  1.1646 +
  1.1647 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1648 +#: ../en/ch01-intro.xml:91
  1.1649 +msgid ""
  1.1650 +"No revision control tool can rescue a poorly run project, but a good choice "
  1.1651 +"of tools can make a huge difference to the fluidity with which you can work "
  1.1652 +"on a project."
  1.1653 +msgstr ""
  1.1654 +
  1.1655 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.1656 +#: ../en/ch01-intro.xml:97
  1.1657 +msgid "The many names of revision control"
  1.1658 +msgstr "版本控制的别名"
  1.1659 +
  1.1660 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1661 +#: ../en/ch01-intro.xml:99
  1.1662 +msgid ""
  1.1663 +"Revision control is a diverse field, so much so that it doesn't actually have "
  1.1664 +"a single name or acronym.  Here are a few of the more common names and "
  1.1665 +"acronyms you'll encounter:"
  1.1666 +msgstr ""
  1.1667 +
  1.1668 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1669 +#: ../en/ch01-intro.xml:104
  1.1670 +msgid "Revision control (RCS)"
  1.1671 +msgstr ""
  1.1672 +
  1.1673 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1674 +#: ../en/ch01-intro.xml:105
  1.1675 +msgid "Software configuration management (SCM), or configuration management"
  1.1676 +msgstr ""
  1.1677 +
  1.1678 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1679 +#: ../en/ch01-intro.xml:107
  1.1680 +msgid "Source code management"
  1.1681 +msgstr ""
  1.1682 +
  1.1683 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1684 +#: ../en/ch01-intro.xml:108
  1.1685 +msgid "Source code control, or source control"
  1.1686 +msgstr ""
  1.1687 +
  1.1688 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.1689 +#: ../en/ch01-intro.xml:110
  1.1690 +msgid "Version control (VCS)"
  1.1691 +msgstr ""
  1.1692 +
  1.1693 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1694 +#: ../en/ch01-intro.xml:112
  1.1695 +msgid ""
  1.1696 +"Some people claim that these terms actually have different meanings, but in "
  1.1697 +"practice they overlap so much that there's no agreed or even useful way to "
  1.1698 +"tease them apart."
  1.1699 +msgstr ""
  1.1700 +
  1.1701 +#. type: Content of: <book><chapter><sect1><title>
  1.1702 +#: ../en/ch01-intro.xml:119
  1.1703 +msgid "A short history of revision control"
  1.1704 +msgstr "版本控制简史"
  1.1705 +
  1.1706 +#. type: Content of: <book><chapter><sect1><para>
  1.1707 +#: ../en/ch01-intro.xml:121
  1.1708 +msgid ""
  1.1709 +"The best known of the old-time revision control tools is SCCS (Source Code "
  1.1710 +"Control System), which Marc Rochkind wrote at Bell Labs, in the early 1970s.  "
  1.1711 +"SCCS operated on individual files, and required every person working on a "
  1.1712 +"project to have access to a shared workspace on a single system.  Only one "
  1.1713 +"person could modify a file at any time; arbitration for access to files was "
  1.1714 +"via locks.  It was common for people to lock files, and later forget to "
  1.1715 +"unlock them, preventing anyone else from modifying those files without the "
  1.1716 +"help of an administrator."
  1.1717 +msgstr ""
  1.1718 +
  1.1719 +#. type: Content of: <book><chapter><sect1><para>
  1.1720 +#: ../en/ch01-intro.xml:132
  1.1721 +msgid ""
  1.1722 +"Walter Tichy developed a free alternative to SCCS in the early 1980s; he "
  1.1723 +"called his program RCS (Revision Control System).  Like SCCS, RCS required "
  1.1724 +"developers to work in a single shared workspace, and to lock files to prevent "
  1.1725 +"multiple people from modifying them simultaneously."
  1.1726 +msgstr ""
  1.1727 +
  1.1728 +#. type: Content of: <book><chapter><sect1><para>
  1.1729 +#: ../en/ch01-intro.xml:138
  1.1730 +msgid ""
  1.1731 +"Later in the 1980s, Dick Grune used RCS as a building block for a set of "
  1.1732 +"shell scripts he initially called cmt, but then renamed to CVS (Concurrent "
  1.1733 +"Versions System).  The big innovation of CVS was that it let developers work "
  1.1734 +"simultaneously and somewhat independently in their own personal workspaces.  "
  1.1735 +"The personal workspaces prevented developers from stepping on each other's "
  1.1736 +"toes all the time, as was common with SCCS and RCS. Each developer had a copy "
  1.1737 +"of every project file, and could modify their copies independently.  They had "
  1.1738 +"to merge their edits prior to committing changes to the central repository."
  1.1739 +msgstr ""
  1.1740 +
  1.1741 +#. type: Content of: <book><chapter><sect1><para>
  1.1742 +#: ../en/ch01-intro.xml:149
  1.1743 +msgid ""
  1.1744 +"Brian Berliner took Grune's original scripts and rewrote them in C, releasing "
  1.1745 +"in 1989 the code that has since developed into the modern version of CVS.  "
  1.1746 +"CVS subsequently acquired the ability to operate over a network connection, "
  1.1747 +"giving it a client/server architecture.  CVS's architecture is centralised; "
  1.1748 +"only the server has a copy of the history of the project. Client workspaces "
  1.1749 +"just contain copies of recent versions of the project's files, and a little "
  1.1750 +"metadata to tell them where the server is.  CVS has been enormously "
  1.1751 +"successful; it is probably the world's most widely used revision control "
  1.1752 +"system."
  1.1753 +msgstr ""
  1.1754 +
  1.1755 +#. type: Content of: <book><chapter><sect1><para>
  1.1756 +#: ../en/ch01-intro.xml:160
  1.1757 +msgid ""
  1.1758 +"In the early 1990s, Sun Microsystems developed an early distributed revision "
  1.1759 +"control system, called TeamWare.  A TeamWare workspace contains a complete "
  1.1760 +"copy of the project's history.  TeamWare has no notion of a central "
  1.1761 +"repository.  (CVS relied upon RCS for its history storage; TeamWare used "
  1.1762 +"SCCS.)"
  1.1763 +msgstr ""
  1.1764 +
  1.1765 +#. type: Content of: <book><chapter><sect1><para>
  1.1766 +#: ../en/ch01-intro.xml:167
  1.1767 +msgid ""
  1.1768 +"As the 1990s progressed, awareness grew of a number of problems with CVS.  It "
  1.1769 +"records simultaneous changes to multiple files individually, instead of "
  1.1770 +"grouping them together as a single logically atomic operation.  It does not "
  1.1771 +"manage its file hierarchy well; it is easy to make a mess of a repository by "
  1.1772 +"renaming files and directories.  Worse, its source code is difficult to read "
  1.1773 +"and maintain, which made the <quote>pain level</quote> of fixing these "
  1.1774 +"architectural problems prohibitive."
  1.1775 +msgstr ""
  1.1776 +
  1.1777 +#. type: Content of: <book><chapter><sect1><para>
  1.1778 +#: ../en/ch01-intro.xml:177
  1.1779 +msgid ""
  1.1780 +"In 2001, Jim Blandy and Karl Fogel, two developers who had worked on CVS, "
  1.1781 +"started a project to replace it with a tool that would have a better "
  1.1782 +"architecture and cleaner code.  The result, Subversion, does not stray from "
  1.1783 +"CVS's centralised client/server model, but it adds multi-file atomic commits, "
  1.1784 +"better namespace management, and a number of other features that make it a "
  1.1785 +"generally better tool than CVS. Since its initial release, it has rapidly "
  1.1786 +"grown in popularity."
  1.1787 +msgstr ""
  1.1788 +
  1.1789 +#. type: Content of: <book><chapter><sect1><para>
  1.1790 +#: ../en/ch01-intro.xml:186
  1.1791 +msgid ""
  1.1792 +"More or less simultaneously, Graydon Hoare began working on an ambitious "
  1.1793 +"distributed revision control system that he named Monotone. While Monotone "
  1.1794 +"addresses many of CVS's design flaws and has a peer-to-peer architecture, it "
  1.1795 +"goes beyond earlier (and subsequent) revision control tools in a number of "
  1.1796 +"innovative ways.  It uses cryptographic hashes as identifiers, and has an "
  1.1797 +"integral notion of <quote>trust</quote> for code from different sources."
  1.1798 +msgstr ""
  1.1799 +
  1.1800 +#. type: Content of: <book><chapter><sect1><para>
  1.1801 +#: ../en/ch01-intro.xml:195
  1.1802 +msgid ""
  1.1803 +"Mercurial began life in 2005.  While a few aspects of its design are "
  1.1804 +"influenced by Monotone, Mercurial focuses on ease of use, high performance, "
  1.1805 +"and scalability to very large projects."
  1.1806 +msgstr ""
  1.1807 +
  1.1808 +#. type: Content of: <book><chapter><sect1><title>
  1.1809 +#: ../en/ch01-intro.xml:202
  1.1810 +msgid "Trends in revision control"
  1.1811 +msgstr "版本控制的发展趋势"
  1.1812 +
  1.1813 +#. type: Content of: <book><chapter><sect1><para>
  1.1814 +#: ../en/ch01-intro.xml:204
  1.1815 +msgid ""
  1.1816 +"There has been an unmistakable trend in the development and use of revision "
  1.1817 +"control tools over the past four decades, as people have become familiar with "
  1.1818 +"the capabilities of their tools and constrained by their limitations."
  1.1819 +msgstr ""
  1.1820 +
  1.1821 +#. type: Content of: <book><chapter><sect1><para>
  1.1822 +#: ../en/ch01-intro.xml:209
  1.1823 +msgid ""
  1.1824 +"The first generation began by managing single files on individual computers.  "
  1.1825 +"Although these tools represented a huge advance over ad-hoc manual revision "
  1.1826 +"control, their locking model and reliance on a single computer limited them "
  1.1827 +"to small, tightly-knit teams."
  1.1828 +msgstr ""
  1.1829 +
  1.1830 +#. type: Content of: <book><chapter><sect1><para>
  1.1831 +#: ../en/ch01-intro.xml:215
  1.1832 +msgid ""
  1.1833 +"The second generation loosened these constraints by moving to network-"
  1.1834 +"centered architectures, and managing entire projects at a time.  As projects "
  1.1835 +"grew larger, they ran into new problems.  With clients needing to talk to "
  1.1836 +"servers very frequently, server scaling became an issue for large projects.  "
  1.1837 +"An unreliable network connection could prevent remote users from being able "
  1.1838 +"to talk to the server at all.  As open source projects started making read-"
  1.1839 +"only access available anonymously to anyone, people without commit privileges "
  1.1840 +"found that they could not use the tools to interact with a project in a "
  1.1841 +"natural way, as they could not record their changes."
  1.1842 +msgstr ""
  1.1843 +
  1.1844 +#. type: Content of: <book><chapter><sect1><para>
  1.1845 +#: ../en/ch01-intro.xml:227
  1.1846 +msgid ""
  1.1847 +"The current generation of revision control tools is peer-to-peer in nature.  "
  1.1848 +"All of these systems have dropped the dependency on a single central server, "
  1.1849 +"and allow people to distribute their revision control data to where it's "
  1.1850 +"actually needed.  Collaboration over the Internet has moved from constrained "
  1.1851 +"by technology to a matter of choice and consensus.  Modern tools can operate "
  1.1852 +"offline indefinitely and autonomously, with a network connection only needed "
  1.1853 +"when syncing changes with another repository."
  1.1854 +msgstr ""
  1.1855 +
  1.1856 +#. type: Content of: <book><chapter><sect1><title>
  1.1857 +#: ../en/ch01-intro.xml:239
  1.1858 +msgid "A few of the advantages of distributed revision control"
  1.1859 +msgstr "分布版本控制的优点"
  1.1860 +
  1.1861 +#. type: Content of: <book><chapter><sect1><para>
  1.1862 +#: ../en/ch01-intro.xml:242
  1.1863 +msgid ""
  1.1864 +"Even though distributed revision control tools have for several years been as "
  1.1865 +"robust and usable as their previous-generation counterparts, people using "
  1.1866 +"older tools have not yet necessarily woken up to their advantages.  There are "
  1.1867 +"a number of ways in which distributed tools shine relative to centralised "
  1.1868 +"ones."
  1.1869 +msgstr ""
  1.1870 +
  1.1871 +#. type: Content of: <book><chapter><sect1><para>
  1.1872 +#: ../en/ch01-intro.xml:249
  1.1873 +msgid ""
  1.1874 +"For an individual developer, distributed tools are almost always much faster "
  1.1875 +"than centralised tools.  This is for a simple reason: a centralised tool "
  1.1876 +"needs to talk over the network for many common operations, because most "
  1.1877 +"metadata is stored in a single copy on the central server.  A distributed "
  1.1878 +"tool stores all of its metadata locally.  All else being equal, talking over "
  1.1879 +"the network adds overhead to a centralised tool.  Don't underestimate the "
  1.1880 +"value of a snappy, responsive tool: you're going to spend a lot of time "
  1.1881 +"interacting with your revision control software."
  1.1882 +msgstr ""
  1.1883 +
  1.1884 +#. type: Content of: <book><chapter><sect1><para>
  1.1885 +#: ../en/ch01-intro.xml:260
  1.1886 +msgid ""
  1.1887 +"Distributed tools are indifferent to the vagaries of your server "
  1.1888 +"infrastructure, again because they replicate metadata to so many locations.  "
  1.1889 +"If you use a centralised system and your server catches fire, you'd better "
  1.1890 +"hope that your backup media are reliable, and that your last backup was "
  1.1891 +"recent and actually worked.  With a distributed tool, you have many backups "
  1.1892 +"available on every contributor's computer."
  1.1893 +msgstr ""
  1.1894 +
  1.1895 +#. type: Content of: <book><chapter><sect1><para>
  1.1896 +#: ../en/ch01-intro.xml:268
  1.1897 +msgid ""
  1.1898 +"The reliability of your network will affect distributed tools far less than "
  1.1899 +"it will centralised tools.  You can't even use a centralised tool without a "
  1.1900 +"network connection, except for a few highly constrained commands.  With a "
  1.1901 +"distributed tool, if your network connection goes down while you're working, "
  1.1902 +"you may not even notice.  The only thing you won't be able to do is talk to "
  1.1903 +"repositories on other computers, something that is relatively rare compared "
  1.1904 +"with local operations.  If you have a far-flung team of collaborators, this "
  1.1905 +"may be significant."
  1.1906 +msgstr ""
  1.1907 +
  1.1908 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.1909 +#: ../en/ch01-intro.xml:279
  1.1910 +msgid "Advantages for open source projects"
  1.1911 +msgstr "开源项目的优点"
  1.1912 +
  1.1913 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.1914 +#: ../en/ch01-intro.xml:281
  1.1915 +msgid ""
  1.1916 +"If you take a shine to an open source project and decide that you would like "
  1.1917 +"to start hacking on it, and that project uses a distributed revision control "
  1.1918 +"tool, you are at once a peer with the people who consider themselves the "
  1.1919 +"<quote>core</quote> of that project.  If they publish their repositories, you "
  1.1920 +"can immediately copy their project history, start making changes, and record "
  1.1921 +"your work, using the same tools in the same ways as insiders.  By contrast, "
  1.1922 +"with a centralised tool, you must use the software in a <quote>read only</"
  1.1923 +"quote> mode unless someone grants you permission to commit changes to their "
  1.1924 +"central server.  Until then, you won't be able to record changes, and your "
  1.1925 +"local modifications will be at risk of corruption any time you try to update "
  1.1926 +"your client's view of the repository."
  1.1927 +msgstr ""
  1.1928 +
  1.1929 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.1930 +#: ../en/ch01-intro.xml:297
  1.1931 +msgid "The forking non-problem"
  1.1932 +msgstr ""
  1.1933 +
  1.1934 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.1935 +#: ../en/ch01-intro.xml:299
  1.1936 +msgid ""
  1.1937 +"It has been suggested that distributed revision control tools pose some sort "
  1.1938 +"of risk to open source projects because they make it easy to <quote>fork</"
  1.1939 +"quote> the development of a project.  A fork happens when there are "
  1.1940 +"differences in opinion or attitude between groups of developers that cause "
  1.1941 +"them to decide that they can't work together any longer.  Each side takes a "
  1.1942 +"more or less complete copy of the project's source code, and goes off in its "
  1.1943 +"own direction."
  1.1944 +msgstr ""
  1.1945 +
  1.1946 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.1947 +#: ../en/ch01-intro.xml:309
  1.1948 +msgid ""
  1.1949 +"Sometimes the camps in a fork decide to reconcile their differences. With a "
  1.1950 +"centralised revision control system, the <emphasis>technical</emphasis> "
  1.1951 +"process of reconciliation is painful, and has to be performed largely by "
  1.1952 +"hand.  You have to decide whose revision history is going to <quote>win</"
  1.1953 +"quote>, and graft the other team's changes into the tree somehow. This "
  1.1954 +"usually loses some or all of one side's revision history."
  1.1955 +msgstr ""
  1.1956 +
  1.1957 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.1958 +#: ../en/ch01-intro.xml:318
  1.1959 +msgid ""
  1.1960 +"What distributed tools do with respect to forking is they make forking the "
  1.1961 +"<emphasis>only</emphasis> way to develop a project.  Every single change that "
  1.1962 +"you make is potentially a fork point.  The great strength of this approach is "
  1.1963 +"that a distributed revision control tool has to be really good at "
  1.1964 +"<emphasis>merging</emphasis> forks, because forks are absolutely fundamental: "
  1.1965 +"they happen all the time."
  1.1966 +msgstr ""
  1.1967 +
  1.1968 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.1969 +#: ../en/ch01-intro.xml:327
  1.1970 +msgid ""
  1.1971 +"If every piece of work that everybody does, all the time, is framed in terms "
  1.1972 +"of forking and merging, then what the open source world refers to as a "
  1.1973 +"<quote>fork</quote> becomes <emphasis>purely</emphasis> a social issue.  If "
  1.1974 +"anything, distributed tools <emphasis>lower</emphasis> the likelihood of a "
  1.1975 +"fork:"
  1.1976 +msgstr ""
  1.1977 +
  1.1978 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.1979 +#: ../en/ch01-intro.xml:334
  1.1980 +msgid ""
  1.1981 +"They eliminate the social distinction that centralised tools impose: that "
  1.1982 +"between insiders (people with commit access) and outsiders (people without)."
  1.1983 +msgstr ""
  1.1984 +
  1.1985 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.1986 +#: ../en/ch01-intro.xml:338
  1.1987 +msgid ""
  1.1988 +"They make it easier to reconcile after a social fork, because all that's "
  1.1989 +"involved from the perspective of the revision control software is just "
  1.1990 +"another merge."
  1.1991 +msgstr ""
  1.1992 +
  1.1993 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.1994 +#: ../en/ch01-intro.xml:343
  1.1995 +msgid ""
  1.1996 +"Some people resist distributed tools because they want to retain tight "
  1.1997 +"control over their projects, and they believe that centralised tools give "
  1.1998 +"them this control.  However, if you're of this belief, and you publish your "
  1.1999 +"CVS or Subversion repositories publicly, there are plenty of tools available "
  1.2000 +"that can pull out your entire project's history (albeit slowly) and recreate "
  1.2001 +"it somewhere that you don't control.  So while your control in this case is "
  1.2002 +"illusory, you are forgoing the ability to fluidly collaborate with whatever "
  1.2003 +"people feel compelled to mirror and fork your history."
  1.2004 +msgstr ""
  1.2005 +
  1.2006 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2007 +#: ../en/ch01-intro.xml:358
  1.2008 +msgid "Advantages for commercial projects"
  1.2009 +msgstr "商业项目的优点"
  1.2010 +
  1.2011 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2012 +#: ../en/ch01-intro.xml:360
  1.2013 +msgid ""
  1.2014 +"Many commercial projects are undertaken by teams that are scattered across "
  1.2015 +"the globe.  Contributors who are far from a central server will see slower "
  1.2016 +"command execution and perhaps less reliability.  Commercial revision control "
  1.2017 +"systems attempt to ameliorate these problems with remote-site replication add-"
  1.2018 +"ons that are typically expensive to buy and cantankerous to administer.  A "
  1.2019 +"distributed system doesn't suffer from these problems in the first place.  "
  1.2020 +"Better yet, you can easily set up multiple authoritative servers, say one per "
  1.2021 +"site, so that there's no redundant communication between repositories over "
  1.2022 +"expensive long-haul network links."
  1.2023 +msgstr ""
  1.2024 +
  1.2025 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2026 +#: ../en/ch01-intro.xml:372
  1.2027 +msgid ""
  1.2028 +"Centralised revision control systems tend to have relatively low "
  1.2029 +"scalability.  It's not unusual for an expensive centralised system to fall "
  1.2030 +"over under the combined load of just a few dozen concurrent users.  Once "
  1.2031 +"again, the typical response tends to be an expensive and clunky replication "
  1.2032 +"facility.  Since the load on a central server---if you have one at all---is "
  1.2033 +"many times lower with a distributed tool (because all of the data is "
  1.2034 +"replicated everywhere), a single cheap server can handle the needs of a much "
  1.2035 +"larger team, and replication to balance load becomes a simple matter of "
  1.2036 +"scripting."
  1.2037 +msgstr ""
  1.2038 +
  1.2039 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2040 +#: ../en/ch01-intro.xml:384
  1.2041 +msgid ""
  1.2042 +"If you have an employee in the field, troubleshooting a problem at a "
  1.2043 +"customer's site, they'll benefit from distributed revision control. The tool "
  1.2044 +"will let them generate custom builds, try different fixes in isolation from "
  1.2045 +"each other, and search efficiently through history for the sources of bugs "
  1.2046 +"and regressions in the customer's environment, all without needing to connect "
  1.2047 +"to your company's network."
  1.2048 +msgstr ""
  1.2049 +
  1.2050 +#. type: Content of: <book><chapter><sect1><title>
  1.2051 +#: ../en/ch01-intro.xml:395
  1.2052 +msgid "Why choose Mercurial?"
  1.2053 +msgstr "为什么选择 Mercurial?"
  1.2054 +
  1.2055 +#. type: Content of: <book><chapter><sect1><para>
  1.2056 +#: ../en/ch01-intro.xml:397
  1.2057 +msgid ""
  1.2058 +"Mercurial has a unique set of properties that make it a particularly good "
  1.2059 +"choice as a revision control system."
  1.2060 +msgstr ""
  1.2061 +
  1.2062 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2063 +#: ../en/ch01-intro.xml:400
  1.2064 +msgid "It is easy to learn and use."
  1.2065 +msgstr ""
  1.2066 +
  1.2067 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2068 +#: ../en/ch01-intro.xml:401
  1.2069 +msgid "It is lightweight."
  1.2070 +msgstr ""
  1.2071 +
  1.2072 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2073 +#: ../en/ch01-intro.xml:402
  1.2074 +msgid "It scales excellently."
  1.2075 +msgstr ""
  1.2076 +
  1.2077 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2078 +#: ../en/ch01-intro.xml:403
  1.2079 +msgid "It is easy to customise."
  1.2080 +msgstr ""
  1.2081 +
  1.2082 +#. type: Content of: <book><chapter><sect1><para>
  1.2083 +#: ../en/ch01-intro.xml:406
  1.2084 +msgid ""
  1.2085 +"If you are at all familiar with revision control systems, you should be able "
  1.2086 +"to get up and running with Mercurial in less than five minutes.  Even if not, "
  1.2087 +"it will take no more than a few minutes longer.  Mercurial's command and "
  1.2088 +"feature sets are generally uniform and consistent, so you can keep track of a "
  1.2089 +"few general rules instead of a host of exceptions."
  1.2090 +msgstr ""
  1.2091 +
  1.2092 +#. type: Content of: <book><chapter><sect1><para>
  1.2093 +#: ../en/ch01-intro.xml:413
  1.2094 +msgid ""
  1.2095 +"On a small project, you can start working with Mercurial in moments. Creating "
  1.2096 +"new changes and branches; transferring changes around (whether locally or "
  1.2097 +"over a network); and history and status operations are all fast.  Mercurial "
  1.2098 +"attempts to stay nimble and largely out of your way by combining low "
  1.2099 +"cognitive overhead with blazingly fast operations."
  1.2100 +msgstr ""
  1.2101 +
  1.2102 +#. type: Content of: <book><chapter><sect1><para>
  1.2103 +#: ../en/ch01-intro.xml:420
  1.2104 +msgid ""
  1.2105 +"The usefulness of Mercurial is not limited to small projects: it is used by "
  1.2106 +"projects with hundreds to thousands of contributors, each containing tens of "
  1.2107 +"thousands of files and hundreds of megabytes of source code."
  1.2108 +msgstr ""
  1.2109 +
  1.2110 +#. type: Content of: <book><chapter><sect1><para>
  1.2111 +#: ../en/ch01-intro.xml:425
  1.2112 +msgid ""
  1.2113 +"If the core functionality of Mercurial is not enough for you, it's easy to "
  1.2114 +"build on.  Mercurial is well suited to scripting tasks, and its clean "
  1.2115 +"internals and implementation in Python make it easy to add features in the "
  1.2116 +"form of extensions.  There are a number of popular and useful extensions "
  1.2117 +"already available, ranging from helping to identify bugs to improving "
  1.2118 +"performance."
  1.2119 +msgstr ""
  1.2120 +
  1.2121 +#. type: Content of: <book><chapter><sect1><title>
  1.2122 +#: ../en/ch01-intro.xml:435
  1.2123 +msgid "Mercurial compared with other tools"
  1.2124 +msgstr "Mercurial 与其它工具的比较"
  1.2125 +
  1.2126 +#. type: Content of: <book><chapter><sect1><para>
  1.2127 +#: ../en/ch01-intro.xml:437
  1.2128 +msgid ""
  1.2129 +"Before you read on, please understand that this section necessarily reflects "
  1.2130 +"my own experiences, interests, and (dare I say it) biases.  I have used every "
  1.2131 +"one of the revision control tools listed below, in most cases for several "
  1.2132 +"years at a time."
  1.2133 +msgstr ""
  1.2134 +
  1.2135 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2136 +#: ../en/ch01-intro.xml:445 ../en/ch01-intro.xml:656
  1.2137 +msgid "Subversion"
  1.2138 +msgstr ""
  1.2139 +
  1.2140 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2141 +#: ../en/ch01-intro.xml:447
  1.2142 +msgid ""
  1.2143 +"Subversion is a popular revision control tool, developed to replace CVS.  It "
  1.2144 +"has a centralised client/server architecture."
  1.2145 +msgstr ""
  1.2146 +
  1.2147 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2148 +#: ../en/ch01-intro.xml:451
  1.2149 +msgid ""
  1.2150 +"Subversion and Mercurial have similarly named commands for performing the "
  1.2151 +"same operations, so if you're familiar with one, it is easy to learn to use "
  1.2152 +"the other.  Both tools are portable to all popular operating systems."
  1.2153 +msgstr ""
  1.2154 +
  1.2155 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2156 +#: ../en/ch01-intro.xml:456
  1.2157 +msgid ""
  1.2158 +"Prior to version 1.5, Subversion had no useful support for merges. At the "
  1.2159 +"time of writing, its merge tracking capability is new, and known to be <ulink "
  1.2160 +"url=\"http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced."
  1.2161 +"html#svn.branchmerge.advanced.finalword\">complicated and buggy</ulink>."
  1.2162 +msgstr ""
  1.2163 +
  1.2164 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2165 +#: ../en/ch01-intro.xml:462
  1.2166 +msgid ""
  1.2167 +"Mercurial has a substantial performance advantage over Subversion on every "
  1.2168 +"revision control operation I have benchmarked.  I have measured its advantage "
  1.2169 +"as ranging from a factor of two to a factor of six when compared with "
  1.2170 +"Subversion 1.4.3's <emphasis>ra_local</emphasis> file store, which is the "
  1.2171 +"fastest access method available.  In more realistic deployments involving a "
  1.2172 +"network-based store, Subversion will be at a substantially larger "
  1.2173 +"disadvantage.  Because many Subversion commands must talk to the server and "
  1.2174 +"Subversion does not have useful replication facilities, server capacity and "
  1.2175 +"network bandwidth become bottlenecks for modestly large projects."
  1.2176 +msgstr ""
  1.2177 +
  1.2178 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2179 +#: ../en/ch01-intro.xml:475
  1.2180 +msgid ""
  1.2181 +"Additionally, Subversion incurs substantial storage overhead to avoid network "
  1.2182 +"transactions for a few common operations, such as finding modified files "
  1.2183 +"(<literal>status</literal>) and displaying modifications against the current "
  1.2184 +"revision (<literal>diff</literal>).  As a result, a Subversion working copy "
  1.2185 +"is often the same size as, or larger than, a Mercurial repository and working "
  1.2186 +"directory, even though the Mercurial repository contains a complete history "
  1.2187 +"of the project."
  1.2188 +msgstr ""
  1.2189 +
  1.2190 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2191 +#: ../en/ch01-intro.xml:485
  1.2192 +msgid ""
  1.2193 +"Subversion is widely supported by third party tools.  Mercurial currently "
  1.2194 +"lags considerably in this area.  This gap is closing, however, and indeed "
  1.2195 +"some of Mercurial's GUI tools now outshine their Subversion equivalents.  "
  1.2196 +"Like Mercurial, Subversion has an excellent user manual."
  1.2197 +msgstr ""
  1.2198 +
  1.2199 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2200 +#: ../en/ch01-intro.xml:491
  1.2201 +msgid ""
  1.2202 +"Because Subversion doesn't store revision history on the client, it is well "
  1.2203 +"suited to managing projects that deal with lots of large, opaque binary "
  1.2204 +"files.  If you check in fifty revisions to an incompressible 10MB file, "
  1.2205 +"Subversion's client-side space usage stays constant The space used by any "
  1.2206 +"distributed SCM will grow rapidly in proportion to the number of revisions, "
  1.2207 +"because the differences between each revision are large."
  1.2208 +msgstr ""
  1.2209 +
  1.2210 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2211 +#: ../en/ch01-intro.xml:500
  1.2212 +msgid ""
  1.2213 +"In addition, it's often difficult or, more usually, impossible to merge "
  1.2214 +"different versions of a binary file.  Subversion's ability to let a user lock "
  1.2215 +"a file, so that they temporarily have the exclusive right to commit changes "
  1.2216 +"to it, can be a significant advantage to a project where binary files are "
  1.2217 +"widely used."
  1.2218 +msgstr ""
  1.2219 +
  1.2220 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2221 +#: ../en/ch01-intro.xml:507
  1.2222 +msgid ""
  1.2223 +"Mercurial can import revision history from a Subversion repository. It can "
  1.2224 +"also export revision history to a Subversion repository.  This makes it easy "
  1.2225 +"to <quote>test the waters</quote> and use Mercurial and Subversion in "
  1.2226 +"parallel before deciding to switch.  History conversion is incremental, so "
  1.2227 +"you can perform an initial conversion, then small additional conversions "
  1.2228 +"afterwards to bring in new changes."
  1.2229 +msgstr ""
  1.2230 +
  1.2231 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2232 +#: ../en/ch01-intro.xml:519 ../en/ch01-intro.xml:658
  1.2233 +msgid "Git"
  1.2234 +msgstr ""
  1.2235 +
  1.2236 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2237 +#: ../en/ch01-intro.xml:521
  1.2238 +msgid ""
  1.2239 +"Git is a distributed revision control tool that was developed for managing "
  1.2240 +"the Linux kernel source tree.  Like Mercurial, its early design was somewhat "
  1.2241 +"influenced by Monotone."
  1.2242 +msgstr ""
  1.2243 +
  1.2244 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2245 +#: ../en/ch01-intro.xml:526
  1.2246 +msgid ""
  1.2247 +"Git has a very large command set, with version 1.5.0 providing 139 individual "
  1.2248 +"commands.  It has something of a reputation for being difficult to learn.  "
  1.2249 +"Compared to Git, Mercurial has a strong focus on simplicity."
  1.2250 +msgstr ""
  1.2251 +
  1.2252 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2253 +#: ../en/ch01-intro.xml:531
  1.2254 +msgid ""
  1.2255 +"In terms of performance, Git is extremely fast.  In several cases, it is "
  1.2256 +"faster than Mercurial, at least on Linux, while Mercurial performs better on "
  1.2257 +"other operations.  However, on Windows, the performance and general level of "
  1.2258 +"support that Git provides is, at the time of writing, far behind that of "
  1.2259 +"Mercurial."
  1.2260 +msgstr ""
  1.2261 +
  1.2262 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2263 +#: ../en/ch01-intro.xml:538
  1.2264 +msgid ""
  1.2265 +"While a Mercurial repository needs no maintenance, a Git repository requires "
  1.2266 +"frequent manual <quote>repacks</quote> of its metadata.  Without these, "
  1.2267 +"performance degrades, while space usage grows rapidly.  A server that "
  1.2268 +"contains many Git repositories that are not rigorously and frequently "
  1.2269 +"repacked will become heavily disk-bound during backups, and there have been "
  1.2270 +"instances of daily backups taking far longer than 24 hours as a result.  A "
  1.2271 +"freshly packed Git repository is slightly smaller than a Mercurial "
  1.2272 +"repository, but an unpacked repository is several orders of magnitude larger."
  1.2273 +msgstr ""
  1.2274 +
  1.2275 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2276 +#: ../en/ch01-intro.xml:549
  1.2277 +msgid ""
  1.2278 +"The core of Git is written in C.  Many Git commands are implemented as shell "
  1.2279 +"or Perl scripts, and the quality of these scripts varies widely. I have "
  1.2280 +"encountered several instances where scripts charged along blindly in the "
  1.2281 +"presence of errors that should have been fatal."
  1.2282 +msgstr ""
  1.2283 +
  1.2284 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2285 +#: ../en/ch01-intro.xml:555
  1.2286 +msgid "Mercurial can import revision history from a Git repository."
  1.2287 +msgstr ""
  1.2288 +
  1.2289 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2290 +#: ../en/ch01-intro.xml:561 ../en/ch01-intro.xml:657
  1.2291 +msgid "CVS"
  1.2292 +msgstr ""
  1.2293 +
  1.2294 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2295 +#: ../en/ch01-intro.xml:563
  1.2296 +msgid ""
  1.2297 +"CVS is probably the most widely used revision control tool in the world.  Due "
  1.2298 +"to its age and internal untidiness, it has been only lightly maintained for "
  1.2299 +"many years."
  1.2300 +msgstr ""
  1.2301 +
  1.2302 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2303 +#: ../en/ch01-intro.xml:567
  1.2304 +msgid ""
  1.2305 +"It has a centralised client/server architecture.  It does not group related "
  1.2306 +"file changes into atomic commits, making it easy for people to <quote>break "
  1.2307 +"the build</quote>: one person can successfully commit part of a change and "
  1.2308 +"then be blocked by the need for a merge, causing other people to see only a "
  1.2309 +"portion of the work they intended to do.  This also affects how you work with "
  1.2310 +"project history.  If you want to see all of the modifications someone made as "
  1.2311 +"part of a task, you will need to manually inspect the descriptions and "
  1.2312 +"timestamps of the changes made to each file involved (if you even know what "
  1.2313 +"those files were)."
  1.2314 +msgstr ""
  1.2315 +
  1.2316 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2317 +#: ../en/ch01-intro.xml:579
  1.2318 +msgid ""
  1.2319 +"CVS has a muddled notion of tags and branches that I will not attempt to even "
  1.2320 +"describe.  It does not support renaming of files or directories well, making "
  1.2321 +"it easy to corrupt a repository.  It has almost no internal consistency "
  1.2322 +"checking capabilities, so it is usually not even possible to tell whether or "
  1.2323 +"how a repository is corrupt.  I would not recommend CVS for any project, "
  1.2324 +"existing or new."
  1.2325 +msgstr ""
  1.2326 +
  1.2327 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2328 +#: ../en/ch01-intro.xml:587
  1.2329 +msgid ""
  1.2330 +"Mercurial can import CVS revision history.  However, there are a few caveats "
  1.2331 +"that apply; these are true of every other revision control tool's CVS "
  1.2332 +"importer, too.  Due to CVS's lack of atomic changes and unversioned "
  1.2333 +"filesystem hierarchy, it is not possible to reconstruct CVS history "
  1.2334 +"completely accurately; some guesswork is involved, and renames will usually "
  1.2335 +"not show up.  Because a lot of advanced CVS administration has to be done by "
  1.2336 +"hand and is hence error-prone, it's common for CVS importers to run into "
  1.2337 +"multiple problems with corrupted repositories (completely bogus revision "
  1.2338 +"timestamps and files that have remained locked for over a decade are just two "
  1.2339 +"of the less interesting problems I can recall from personal experience)."
  1.2340 +msgstr ""
  1.2341 +
  1.2342 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2343 +#: ../en/ch01-intro.xml:601
  1.2344 +msgid "Mercurial can import revision history from a CVS repository."
  1.2345 +msgstr ""
  1.2346 +
  1.2347 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2348 +#: ../en/ch01-intro.xml:607
  1.2349 +msgid "Commercial tools"
  1.2350 +msgstr "商业工具"
  1.2351 +
  1.2352 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2353 +#: ../en/ch01-intro.xml:609
  1.2354 +msgid ""
  1.2355 +"Perforce has a centralised client/server architecture, with no client-side "
  1.2356 +"caching of any data.  Unlike modern revision control tools, Perforce requires "
  1.2357 +"that a user run a command to inform the server about every file they intend "
  1.2358 +"to edit."
  1.2359 +msgstr ""
  1.2360 +
  1.2361 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2362 +#: ../en/ch01-intro.xml:615
  1.2363 +msgid ""
  1.2364 +"The performance of Perforce is quite good for small teams, but it falls off "
  1.2365 +"rapidly as the number of users grows beyond a few dozen. Modestly large "
  1.2366 +"Perforce installations require the deployment of proxies to cope with the "
  1.2367 +"load their users generate."
  1.2368 +msgstr ""
  1.2369 +
  1.2370 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2371 +#: ../en/ch01-intro.xml:624
  1.2372 +msgid "Choosing a revision control tool"
  1.2373 +msgstr "选择版本控制工具"
  1.2374 +
  1.2375 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2376 +#: ../en/ch01-intro.xml:626
  1.2377 +msgid ""
  1.2378 +"With the exception of CVS, all of the tools listed above have unique "
  1.2379 +"strengths that suit them to particular styles of work.  There is no single "
  1.2380 +"revision control tool that is best in all situations."
  1.2381 +msgstr ""
  1.2382 +
  1.2383 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2384 +#: ../en/ch01-intro.xml:631
  1.2385 +msgid ""
  1.2386 +"As an example, Subversion is a good choice for working with frequently edited "
  1.2387 +"binary files, due to its centralised nature and support for file locking."
  1.2388 +msgstr ""
  1.2389 +
  1.2390 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2391 +#: ../en/ch01-intro.xml:635
  1.2392 +msgid ""
  1.2393 +"I personally find Mercurial's properties of simplicity, performance, and good "
  1.2394 +"merge support to be a compelling combination that has served me well for "
  1.2395 +"several years."
  1.2396 +msgstr ""
  1.2397 +
  1.2398 +#. type: Content of: <book><chapter><sect1><title>
  1.2399 +#: ../en/ch01-intro.xml:643
  1.2400 +msgid "Switching from another tool to Mercurial"
  1.2401 +msgstr "从其它工具切换到 Mercurial"
  1.2402 +
  1.2403 +#. type: Content of: <book><chapter><sect1><para>
  1.2404 +#: ../en/ch01-intro.xml:645
  1.2405 +msgid ""
  1.2406 +"Mercurial is bundled with an extension named <literal role=\"hg-ext"
  1.2407 +"\">convert</literal>, which can incrementally import revision history from "
  1.2408 +"several other revision control tools.  By <quote>incremental</quote>, I mean "
  1.2409 +"that you can convert all of a project's history to date in one go, then rerun "
  1.2410 +"the conversion later to obtain new changes that happened after the initial "
  1.2411 +"conversion."
  1.2412 +msgstr ""
  1.2413 +
  1.2414 +#. type: Content of: <book><chapter><sect1><para>
  1.2415 +#: ../en/ch01-intro.xml:653
  1.2416 +msgid ""
  1.2417 +"The revision control tools supported by <literal role=\"hg-ext\">convert</"
  1.2418 +"literal> are as follows:"
  1.2419 +msgstr ""
  1.2420 +
  1.2421 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2422 +#: ../en/ch01-intro.xml:659
  1.2423 +msgid "Darcs"
  1.2424 +msgstr ""
  1.2425 +
  1.2426 +#. type: Content of: <book><chapter><sect1><para>
  1.2427 +#: ../en/ch01-intro.xml:661
  1.2428 +msgid ""
  1.2429 +"In addition, <literal role=\"hg-ext\">convert</literal> can export changes "
  1.2430 +"from Mercurial to Subversion.  This makes it possible to try Subversion and "
  1.2431 +"Mercurial in parallel before committing to a switchover, without risking the "
  1.2432 +"loss of any work."
  1.2433 +msgstr ""
  1.2434 +
  1.2435 +#. type: Content of: <book><chapter><sect1><para>
  1.2436 +#: ../en/ch01-intro.xml:667
  1.2437 +msgid ""
  1.2438 +"The <command role=\"hg-ext-conver\">convert</command> command is easy to "
  1.2439 +"use.  Simply point it at the path or URL of the source repository, optionally "
  1.2440 +"give it the name of the destination repository, and it will start working.  "
  1.2441 +"After the initial conversion, just run the same command again to import new "
  1.2442 +"changes."
  1.2443 +msgstr ""
  1.2444 +
  1.2445 +#. type: Content of: <book><chapter><title>
  1.2446 +#: ../en/ch02-tour-basic.xml:5
  1.2447 +msgid "A tour of Mercurial: the basics"
  1.2448 +msgstr "Mercurial 教程: 基础知识"
  1.2449 +
  1.2450 +#. type: Content of: <book><chapter><sect1><title>
  1.2451 +#: ../en/ch02-tour-basic.xml:8
  1.2452 +msgid "Installing Mercurial on your system"
  1.2453 +msgstr "安装 Mercurial"
  1.2454 +
  1.2455 +#. type: Content of: <book><chapter><sect1><para>
  1.2456 +#: ../en/ch02-tour-basic.xml:10
  1.2457 +msgid ""
  1.2458 +"Prebuilt binary packages of Mercurial are available for every popular "
  1.2459 +"operating system.  These make it easy to start using Mercurial on your "
  1.2460 +"computer immediately."
  1.2461 +msgstr ""
  1.2462 +
  1.2463 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2464 +#: ../en/ch02-tour-basic.xml:15
  1.2465 +msgid "Linux"
  1.2466 +msgstr ""
  1.2467 +
  1.2468 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2469 +#: ../en/ch02-tour-basic.xml:17
  1.2470 +msgid ""
  1.2471 +"Because each Linux distribution has its own packaging tools, policies, and "
  1.2472 +"rate of development, it's difficult to give a comprehensive set of "
  1.2473 +"instructions on how to install Mercurial binaries.  The version of Mercurial "
  1.2474 +"that you will end up with can vary depending on how active the person is who "
  1.2475 +"maintains the package for your distribution."
  1.2476 +msgstr ""
  1.2477 +
  1.2478 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2479 +#: ../en/ch02-tour-basic.xml:24
  1.2480 +msgid ""
  1.2481 +"To keep things simple, I will focus on installing Mercurial from the command "
  1.2482 +"line under the most popular Linux distributions.  Most of these distributions "
  1.2483 +"provide graphical package managers that will let you install Mercurial with a "
  1.2484 +"single click; the package name to look for is <literal>mercurial</literal>."
  1.2485 +msgstr ""
  1.2486 +
  1.2487 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.2488 +#: ../en/ch02-tour-basic.xml:32
  1.2489 +msgid "Debian:"
  1.2490 +msgstr ""
  1.2491 +
  1.2492 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.2493 +#: ../en/ch02-tour-basic.xml:35
  1.2494 +msgid "Fedora Core:"
  1.2495 +msgstr ""
  1.2496 +
  1.2497 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.2498 +#: ../en/ch02-tour-basic.xml:38
  1.2499 +msgid "Gentoo:"
  1.2500 +msgstr ""
  1.2501 +
  1.2502 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.2503 +#: ../en/ch02-tour-basic.xml:40
  1.2504 +msgid "OpenSUSE:"
  1.2505 +msgstr ""
  1.2506 +
  1.2507 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.2508 +#: ../en/ch02-tour-basic.xml:43
  1.2509 +msgid ""
  1.2510 +"Ubuntu: Ubuntu's Mercurial package is based on Debian's.  To install it, run "
  1.2511 +"the following command."
  1.2512 +msgstr ""
  1.2513 +
  1.2514 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2515 +#: ../en/ch02-tour-basic.xml:52
  1.2516 +msgid "Solaris"
  1.2517 +msgstr ""
  1.2518 +
  1.2519 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2520 +#: ../en/ch02-tour-basic.xml:54
  1.2521 +msgid ""
  1.2522 +"SunFreeWare, at <ulink url=\"http://www.sunfreeware.com\">http://www."
  1.2523 +"sunfreeware.com</ulink>, is a good source for a large number of pre-built "
  1.2524 +"Solaris packages for 32 and 64 bit Intel and Sparc architectures, including "
  1.2525 +"current versions of Mercurial."
  1.2526 +msgstr ""
  1.2527 +
  1.2528 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2529 +#: ../en/ch02-tour-basic.xml:62
  1.2530 +msgid "Mac OS X"
  1.2531 +msgstr ""
  1.2532 +
  1.2533 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2534 +#: ../en/ch02-tour-basic.xml:64
  1.2535 +msgid ""
  1.2536 +"Lee Cantey publishes an installer of Mercurial for Mac OS X at <ulink url="
  1.2537 +"\"http://mercurial.berkwood.com\">http://mercurial.berkwood.com</ulink>.  "
  1.2538 +"This package works on both Intel- and Power-based Macs. Before you can use "
  1.2539 +"it, you must install a compatible version of Universal MacPython "
  1.2540 +"<citation>web:macpython</citation>. This is easy to do; simply follow the "
  1.2541 +"instructions on Lee's site."
  1.2542 +msgstr ""
  1.2543 +
  1.2544 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2545 +#: ../en/ch02-tour-basic.xml:73
  1.2546 +msgid ""
  1.2547 +"It's also possible to install Mercurial using Fink or MacPorts, two popular "
  1.2548 +"free package managers for Mac OS X.  If you have Fink, use <command>sudo apt-"
  1.2549 +"get install mercurial-py25</command>.  If MacPorts, <command>sudo port "
  1.2550 +"install mercurial</command>."
  1.2551 +msgstr ""
  1.2552 +
  1.2553 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2554 +#: ../en/ch02-tour-basic.xml:81
  1.2555 +msgid "Windows"
  1.2556 +msgstr ""
  1.2557 +
  1.2558 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2559 +#: ../en/ch02-tour-basic.xml:83
  1.2560 +msgid ""
  1.2561 +"Lee Cantey publishes an installer of Mercurial for Windows at <ulink url="
  1.2562 +"\"http://mercurial.berkwood.com\">http://mercurial.berkwood.com</ulink>.  "
  1.2563 +"This package has no external dependencies; it <quote>just works</quote>."
  1.2564 +msgstr ""
  1.2565 +
  1.2566 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
  1.2567 +#: ../en/ch02-tour-basic.xml:90
  1.2568 +msgid ""
  1.2569 +"The Windows version of Mercurial does not automatically convert line endings "
  1.2570 +"between Windows and Unix styles.  If you want to share work with Unix users, "
  1.2571 +"you must do a little additional configuration work. XXX Flesh this out."
  1.2572 +msgstr ""
  1.2573 +
  1.2574 +#. type: Content of: <book><chapter><sect1><title>
  1.2575 +#: ../en/ch02-tour-basic.xml:100
  1.2576 +msgid "Getting started"
  1.2577 +msgstr "开始"
  1.2578 +
  1.2579 +#. type: Content of: <book><chapter><sect1><para>
  1.2580 +#: ../en/ch02-tour-basic.xml:102
  1.2581 +msgid ""
  1.2582 +"To begin, we'll use the <command role=\"hg-cmd\">hg version</command> command "
  1.2583 +"to find out whether Mercurial is actually installed properly.  The actual "
  1.2584 +"version information that it prints isn't so important; it's whether it prints "
  1.2585 +"anything at all that we care about."
  1.2586 +msgstr ""
  1.2587 +
  1.2588 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2589 +#: ../en/ch02-tour-basic.xml:111
  1.2590 +msgid "Built-in help"
  1.2591 +msgstr "内置帮助"
  1.2592 +
  1.2593 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2594 +#: ../en/ch02-tour-basic.xml:113
  1.2595 +msgid ""
  1.2596 +"Mercurial provides a built-in help system.  This is invaluable for those "
  1.2597 +"times when you find yourself stuck trying to remember how to run a command.  "
  1.2598 +"If you are completely stuck, simply run <command role=\"hg-cmd\">hg help</"
  1.2599 +"command>; it will print a brief list of commands, along with a description of "
  1.2600 +"what each does.  If you ask for help on a specific command (as below), it "
  1.2601 +"prints more detailed information."
  1.2602 +msgstr ""
  1.2603 +
  1.2604 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2605 +#: ../en/ch02-tour-basic.xml:124
  1.2606 +msgid ""
  1.2607 +"For a more impressive level of detail (which you won't usually need) run "
  1.2608 +"<command role=\"hg-cmd\">hg help <option role=\"hg-opt-global\">-v</option></"
  1.2609 +"command>.  The <option role=\"hg-opt-global\">-v</option> option is short for "
  1.2610 +"<option role=\"hg-opt-global\">--verbose</option>, and tells Mercurial to "
  1.2611 +"print more information than it usually would."
  1.2612 +msgstr ""
  1.2613 +
  1.2614 +#. type: Content of: <book><chapter><sect1><title>
  1.2615 +#: ../en/ch02-tour-basic.xml:135
  1.2616 +msgid "Working with a repository"
  1.2617 +msgstr "使用版本库"
  1.2618 +
  1.2619 +#. type: Content of: <book><chapter><sect1><para>
  1.2620 +#: ../en/ch02-tour-basic.xml:137
  1.2621 +msgid ""
  1.2622 +"In Mercurial, everything happens inside a <emphasis>repository</emphasis>.  "
  1.2623 +"The repository for a project contains all of the files that <quote>belong to</"
  1.2624 +"quote> that project, along with a historical record of the project's files."
  1.2625 +msgstr ""
  1.2626 +
  1.2627 +#. type: Content of: <book><chapter><sect1><para>
  1.2628 +#: ../en/ch02-tour-basic.xml:143
  1.2629 +msgid ""
  1.2630 +"There's nothing particularly magical about a repository; it is simply a "
  1.2631 +"directory tree in your filesystem that Mercurial treats as special. You can "
  1.2632 +"rename or delete a repository any time you like, using either the command "
  1.2633 +"line or your file browser."
  1.2634 +msgstr ""
  1.2635 +
  1.2636 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2637 +#: ../en/ch02-tour-basic.xml:150
  1.2638 +msgid "Making a local copy of a repository"
  1.2639 +msgstr "创建版本库的工作副本"
  1.2640 +
  1.2641 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2642 +#: ../en/ch02-tour-basic.xml:152
  1.2643 +msgid ""
  1.2644 +"<emphasis>Copying</emphasis> a repository is just a little bit special.  "
  1.2645 +"While you could use a normal file copying command to make a copy of a "
  1.2646 +"repository, it's best to use a built-in command that Mercurial provides.  "
  1.2647 +"This command is called <command role=\"hg-cmd\">hg clone</command>, because "
  1.2648 +"it creates an identical copy of an existing repository."
  1.2649 +msgstr ""
  1.2650 +
  1.2651 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2652 +#: ../en/ch02-tour-basic.xml:161
  1.2653 +msgid ""
  1.2654 +"If our clone succeeded, we should now have a local directory called <filename "
  1.2655 +"class=\"directory\">hello</filename>.  This directory will contain some files."
  1.2656 +msgstr ""
  1.2657 +
  1.2658 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2659 +#: ../en/ch02-tour-basic.xml:167
  1.2660 +msgid ""
  1.2661 +"These files have the same contents and history in our repository as they do "
  1.2662 +"in the repository we cloned."
  1.2663 +msgstr ""
  1.2664 +
  1.2665 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2666 +#: ../en/ch02-tour-basic.xml:170
  1.2667 +msgid ""
  1.2668 +"Every Mercurial repository is complete, self-contained, and independent.  It "
  1.2669 +"contains its own private copy of a project's files and history.  A cloned "
  1.2670 +"repository remembers the location of the repository it was cloned from, but "
  1.2671 +"it does not communicate with that repository, or any other, unless you tell "
  1.2672 +"it to."
  1.2673 +msgstr ""
  1.2674 +
  1.2675 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2676 +#: ../en/ch02-tour-basic.xml:177
  1.2677 +msgid ""
  1.2678 +"What this means for now is that we're free to experiment with our repository, "
  1.2679 +"safe in the knowledge that it's a private <quote>sandbox</quote> that won't "
  1.2680 +"affect anyone else."
  1.2681 +msgstr ""
  1.2682 +
  1.2683 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2684 +#: ../en/ch02-tour-basic.xml:183
  1.2685 +msgid "What's in a repository?"
  1.2686 +msgstr "什么是版本库?"
  1.2687 +
  1.2688 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2689 +#: ../en/ch02-tour-basic.xml:185
  1.2690 +msgid ""
  1.2691 +"When we take a more detailed look inside a repository, we can see that it "
  1.2692 +"contains a directory named <filename class=\"directory\">.hg</filename>.  "
  1.2693 +"This is where Mercurial keeps all of its metadata for the repository."
  1.2694 +msgstr ""
  1.2695 +
  1.2696 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2697 +#: ../en/ch02-tour-basic.xml:192
  1.2698 +msgid ""
  1.2699 +"The contents of the <filename class=\"directory\">.hg</filename> directory "
  1.2700 +"and its subdirectories are private to Mercurial.  Every other file and "
  1.2701 +"directory in the repository is yours to do with as you please."
  1.2702 +msgstr ""
  1.2703 +
  1.2704 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2705 +#: ../en/ch02-tour-basic.xml:198
  1.2706 +msgid ""
  1.2707 +"To introduce a little terminology, the <filename class=\"directory\">.hg</"
  1.2708 +"filename> directory is the <quote>real</quote> repository, and all of the "
  1.2709 +"files and directories that coexist with it are said to live in the "
  1.2710 +"<emphasis>working directory</emphasis>.  An easy way to remember the "
  1.2711 +"distinction is that the <emphasis>repository</emphasis> contains the "
  1.2712 +"<emphasis>history</emphasis> of your project, while the <emphasis>working "
  1.2713 +"directory</emphasis> contains a <emphasis>snapshot</emphasis> of your project "
  1.2714 +"at a particular point in history."
  1.2715 +msgstr ""
  1.2716 +
  1.2717 +#. type: Content of: <book><chapter><sect1><title>
  1.2718 +#: ../en/ch02-tour-basic.xml:213
  1.2719 +msgid "A tour through history"
  1.2720 +msgstr "回溯历史"
  1.2721 +
  1.2722 +#. type: Content of: <book><chapter><sect1><para>
  1.2723 +#: ../en/ch02-tour-basic.xml:215
  1.2724 +msgid ""
  1.2725 +"One of the first things we might want to do with a new, unfamiliar repository "
  1.2726 +"is understand its history.  The <command role=\"hg-cmd\">hg log</command> "
  1.2727 +"command gives us a view of history."
  1.2728 +msgstr ""
  1.2729 +
  1.2730 +#. type: Content of: <book><chapter><sect1><para>
  1.2731 +#: ../en/ch02-tour-basic.xml:222
  1.2732 +msgid ""
  1.2733 +"By default, this command prints a brief paragraph of output for each change "
  1.2734 +"to the project that was recorded.  In Mercurial terminology, we call each of "
  1.2735 +"these recorded events a <emphasis>changeset</emphasis>, because it can "
  1.2736 +"contain a record of changes to several files."
  1.2737 +msgstr ""
  1.2738 +
  1.2739 +#. type: Content of: <book><chapter><sect1><para>
  1.2740 +#: ../en/ch02-tour-basic.xml:228
  1.2741 +msgid ""
  1.2742 +"The fields in a record of output from <command role=\"hg-cmd\">hg log</"
  1.2743 +"command> are as follows."
  1.2744 +msgstr ""
  1.2745 +
  1.2746 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2747 +#: ../en/ch02-tour-basic.xml:231
  1.2748 +msgid ""
  1.2749 +"<literal>changeset</literal>: This field has the format of a number, followed "
  1.2750 +"by a colon, followed by a hexadecimal string.  These are "
  1.2751 +"<emphasis>identifiers</emphasis> for the changeset.  There are two "
  1.2752 +"identifiers because the number is shorter and easier to type than the hex "
  1.2753 +"string."
  1.2754 +msgstr ""
  1.2755 +
  1.2756 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2757 +#: ../en/ch02-tour-basic.xml:237
  1.2758 +msgid ""
  1.2759 +"<literal>user</literal>: The identity of the person who created the "
  1.2760 +"changeset.  This is a free-form field, but it most often contains a person's "
  1.2761 +"name and email address."
  1.2762 +msgstr ""
  1.2763 +
  1.2764 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2765 +#: ../en/ch02-tour-basic.xml:241
  1.2766 +msgid ""
  1.2767 +"<literal>date</literal>: The date and time on which the changeset was "
  1.2768 +"created, and the timezone in which it was created.  (The date and time are "
  1.2769 +"local to that timezone; they display what time and date it was for the person "
  1.2770 +"who created the changeset.)"
  1.2771 +msgstr ""
  1.2772 +
  1.2773 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2774 +#: ../en/ch02-tour-basic.xml:246
  1.2775 +msgid ""
  1.2776 +"<literal>summary</literal>: The first line of the text message that the "
  1.2777 +"creator of the changeset entered to describe the changeset."
  1.2778 +msgstr ""
  1.2779 +
  1.2780 +#. type: Content of: <book><chapter><sect1><para>
  1.2781 +#: ../en/ch02-tour-basic.xml:249
  1.2782 +msgid ""
  1.2783 +"The default output printed by <command role=\"hg-cmd\">hg log</command> is "
  1.2784 +"purely a summary; it is missing a lot of detail."
  1.2785 +msgstr ""
  1.2786 +
  1.2787 +#. type: Content of: <book><chapter><sect1><para>
  1.2788 +#: ../en/ch02-tour-basic.xml:253
  1.2789 +msgid ""
  1.2790 +"Figure <xref linkend=\"fig.tour-basic.history\"/> provides a graphical "
  1.2791 +"representation of the history of the <filename class=\"directory\">hello</"
  1.2792 +"filename> repository, to make it a little easier to see which direction "
  1.2793 +"history is <quote>flowing</quote> in.  We'll be returning to this figure "
  1.2794 +"several times in this chapter and the chapter that follows."
  1.2795 +msgstr ""
  1.2796 +
  1.2797 +#. type: Content of: <book><chapter><sect1><informalfigure><mediaobject>
  1.2798 +#: ../en/ch02-tour-basic.xml:263
  1.2799 +msgid ""
  1.2800 +"<imageobject><imagedata fileref=\"images/tour-history.png\"/></imageobject>"
  1.2801 +msgstr ""
  1.2802 +
  1.2803 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><textobject><phrase>
  1.2804 +#: ../en/ch02-tour-basic.xml:264 ../en/ch03-tour-merge.xml:48
  1.2805 +#: ../en/ch03-tour-merge.xml:76 ../en/ch03-tour-merge.xml:124
  1.2806 +#: ../en/ch03-tour-merge.xml:181 ../en/ch03-tour-merge.xml:248
  1.2807 +#: ../en/ch04-concepts.xml:54 ../en/ch04-concepts.xml:104
  1.2808 +#: ../en/ch04-concepts.xml:189 ../en/ch04-concepts.xml:293
  1.2809 +#: ../en/ch04-concepts.xml:342 ../en/ch04-concepts.xml:356
  1.2810 +#: ../en/ch04-concepts.xml:396 ../en/ch04-concepts.xml:415
  1.2811 +#: ../en/ch04-concepts.xml:456 ../en/ch06-collab.xml:275
  1.2812 +#: ../en/ch09-undo.xml:363 ../en/ch09-undo.xml:411 ../en/ch09-undo.xml:476
  1.2813 +#: ../en/ch09-undo.xml:516 ../en/ch12-mq.xml:408
  1.2814 +msgid "XXX add text"
  1.2815 +msgstr ""
  1.2816 +
  1.2817 +#. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para>
  1.2818 +#: ../en/ch02-tour-basic.xml:265
  1.2819 +msgid ""
  1.2820 +"Graphical history of the <filename class=\"directory\">hello</filename> "
  1.2821 +"repository"
  1.2822 +msgstr ""
  1.2823 +
  1.2824 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2825 +#: ../en/ch02-tour-basic.xml:272
  1.2826 +msgid "Changesets, revisions, and talking to other people"
  1.2827 +msgstr "改变集，版本，与其它用户交互"
  1.2828 +
  1.2829 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2830 +#: ../en/ch02-tour-basic.xml:275
  1.2831 +msgid ""
  1.2832 +"As English is a notoriously sloppy language, and computer science has a "
  1.2833 +"hallowed history of terminological confusion (why use one term when four will "
  1.2834 +"do?), revision control has a variety of words and phrases that mean the same "
  1.2835 +"thing.  If you are talking about Mercurial history with other people, you "
  1.2836 +"will find that the word <quote>changeset</quote> is often compressed to "
  1.2837 +"<quote>change</quote> or (when written)  <quote>cset</quote>, and sometimes a "
  1.2838 +"changeset is referred to as a <quote>revision</quote> or a <quote>rev</quote>."
  1.2839 +msgstr ""
  1.2840 +
  1.2841 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2842 +#: ../en/ch02-tour-basic.xml:285
  1.2843 +msgid ""
  1.2844 +"While it doesn't matter what <emphasis>word</emphasis> you use to refer to "
  1.2845 +"the concept of <quote>a changeset</quote>, the <emphasis>identifier</"
  1.2846 +"emphasis> that you use to refer to <quote>a <emphasis>specific</emphasis> "
  1.2847 +"changeset</quote> is of great importance. Recall that the <literal>changeset</"
  1.2848 +"literal> field in the output from <command role=\"hg-cmd\">hg log</command> "
  1.2849 +"identifies a changeset using both a number and a hexadecimal string."
  1.2850 +msgstr ""
  1.2851 +
  1.2852 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.2853 +#: ../en/ch02-tour-basic.xml:294
  1.2854 +msgid ""
  1.2855 +"The revision number is <emphasis>only valid in that repository</emphasis>,"
  1.2856 +msgstr ""
  1.2857 +
  1.2858 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.2859 +#: ../en/ch02-tour-basic.xml:296
  1.2860 +msgid ""
  1.2861 +"while the hex string is the <emphasis>permanent, unchanging identifier</"
  1.2862 +"emphasis> that will always identify that exact changeset in <emphasis>every</"
  1.2863 +"emphasis> copy of the repository."
  1.2864 +msgstr ""
  1.2865 +
  1.2866 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2867 +#: ../en/ch02-tour-basic.xml:301
  1.2868 +msgid ""
  1.2869 +"This distinction is important.  If you send someone an email talking about "
  1.2870 +"<quote>revision 33</quote>, there's a high likelihood that their revision 33 "
  1.2871 +"will <emphasis>not be the same</emphasis> as yours.  The reason for this is "
  1.2872 +"that a revision number depends on the order in which changes arrived in a "
  1.2873 +"repository, and there is no guarantee that the same changes will happen in "
  1.2874 +"the same order in different repositories. Three changes $a,b,c$ can easily "
  1.2875 +"appear in one repository as $0,1,2$, while in another as $1,0,2$."
  1.2876 +msgstr ""
  1.2877 +
  1.2878 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2879 +#: ../en/ch02-tour-basic.xml:311
  1.2880 +msgid ""
  1.2881 +"Mercurial uses revision numbers purely as a convenient shorthand.  If you "
  1.2882 +"need to discuss a changeset with someone, or make a record of a changeset for "
  1.2883 +"some other reason (for example, in a bug report), use the hexadecimal "
  1.2884 +"identifier."
  1.2885 +msgstr ""
  1.2886 +
  1.2887 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2888 +#: ../en/ch02-tour-basic.xml:319
  1.2889 +msgid "Viewing specific revisions"
  1.2890 +msgstr "察看指定版本"
  1.2891 +
  1.2892 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2893 +#: ../en/ch02-tour-basic.xml:321
  1.2894 +msgid ""
  1.2895 +"To narrow the output of <command role=\"hg-cmd\">hg log</command> down to a "
  1.2896 +"single revision, use the <option role=\"hg-opt-log\">-r</option> (or <option "
  1.2897 +"role=\"hg-opt-log\">--rev</option>) option.  You can use either a revision "
  1.2898 +"number or a long-form changeset identifier, and you can provide as many "
  1.2899 +"revisions as you want."
  1.2900 +msgstr ""
  1.2901 +
  1.2902 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2903 +#: ../en/ch02-tour-basic.xml:330
  1.2904 +msgid ""
  1.2905 +"If you want to see the history of several revisions without having to list "
  1.2906 +"each one, you can use <emphasis>range notation</emphasis>; this lets you "
  1.2907 +"express the idea <quote>I want all revisions between <literal>abc</literal> "
  1.2908 +"and <literal>def</literal>, inclusive</quote>."
  1.2909 +msgstr ""
  1.2910 +
  1.2911 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2912 +#: ../en/ch02-tour-basic.xml:338
  1.2913 +msgid ""
  1.2914 +"Mercurial also honours the order in which you specify revisions, so <command "
  1.2915 +"role=\"hg-cmd\">hg log -r 2:4</command> prints 2, 3, and 4. while <command "
  1.2916 +"role=\"hg-cmd\">hg log -r 4:2</command> prints 4, 3, and 2."
  1.2917 +msgstr ""
  1.2918 +
  1.2919 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.2920 +#: ../en/ch02-tour-basic.xml:345
  1.2921 +msgid "More detailed information"
  1.2922 +msgstr "更详细的信息"
  1.2923 +
  1.2924 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2925 +#: ../en/ch02-tour-basic.xml:347
  1.2926 +msgid ""
  1.2927 +"While the summary information printed by <command role=\"hg-cmd\">hg log</"
  1.2928 +"command> is useful if you already know what you're looking for, you may need "
  1.2929 +"to see a complete description of the change, or a list of the files changed, "
  1.2930 +"if you're trying to decide whether a changeset is the one you're looking for. "
  1.2931 +"The <command role=\"hg-cmd\">hg log</command> command's <option role=\"hg-opt-"
  1.2932 +"global\">-v</option> (or <option role=\"hg-opt-global\">--verbose</option>) "
  1.2933 +"option gives you this extra detail."
  1.2934 +msgstr ""
  1.2935 +
  1.2936 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.2937 +#: ../en/ch02-tour-basic.xml:359
  1.2938 +msgid ""
  1.2939 +"If you want to see both the description and content of a change, add the "
  1.2940 +"<option role=\"hg-opt-log\">-p</option> (or <option role=\"hg-opt-log\">--"
  1.2941 +"patch</option>) option.  This displays the content of a change as a "
  1.2942 +"<emphasis>unified diff</emphasis> (if you've never seen a unified diff "
  1.2943 +"before, see section <xref linkend=\"sec.mq.patch\"/> for an overview)."
  1.2944 +msgstr ""
  1.2945 +
  1.2946 +#. type: Content of: <book><chapter><sect1><title>
  1.2947 +#: ../en/ch02-tour-basic.xml:372
  1.2948 +msgid "All about command options"
  1.2949 +msgstr "命令选项"
  1.2950 +
  1.2951 +#. type: Content of: <book><chapter><sect1><para>
  1.2952 +#: ../en/ch02-tour-basic.xml:374
  1.2953 +msgid ""
  1.2954 +"Let's take a brief break from exploring Mercurial commands to discuss a "
  1.2955 +"pattern in the way that they work; you may find this useful to keep in mind "
  1.2956 +"as we continue our tour."
  1.2957 +msgstr ""
  1.2958 +
  1.2959 +#. type: Content of: <book><chapter><sect1><para>
  1.2960 +#: ../en/ch02-tour-basic.xml:378
  1.2961 +msgid ""
  1.2962 +"Mercurial has a consistent and straightforward approach to dealing with the "
  1.2963 +"options that you can pass to commands.  It follows the conventions for "
  1.2964 +"options that are common to modern Linux and Unix systems."
  1.2965 +msgstr ""
  1.2966 +
  1.2967 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2968 +#: ../en/ch02-tour-basic.xml:383
  1.2969 +msgid ""
  1.2970 +"Every option has a long name.  For example, as we've already seen, the "
  1.2971 +"<command role=\"hg-cmd\">hg log</command> command accepts a <option role=\"hg-"
  1.2972 +"opt-log\">--rev</option> option."
  1.2973 +msgstr ""
  1.2974 +
  1.2975 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2976 +#: ../en/ch02-tour-basic.xml:387
  1.2977 +msgid ""
  1.2978 +"Most options have short names, too.  Instead of <option role=\"hg-opt-log\">--"
  1.2979 +"rev</option>, we can use <option role=\"hg-opt-log\">-r</option>.  (The "
  1.2980 +"reason that some options don't have short names is that the options in "
  1.2981 +"question are rarely used.)"
  1.2982 +msgstr ""
  1.2983 +
  1.2984 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2985 +#: ../en/ch02-tour-basic.xml:392
  1.2986 +msgid ""
  1.2987 +"Long options start with two dashes (e.g. <option role=\"hg-opt-log\">--rev</"
  1.2988 +"option>), while short options start with one (e.g. <option role=\"hg-opt-log"
  1.2989 +"\">-r</option>)."
  1.2990 +msgstr ""
  1.2991 +
  1.2992 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.2993 +#: ../en/ch02-tour-basic.xml:396
  1.2994 +msgid ""
  1.2995 +"Option naming and usage is consistent across commands.  For example, every "
  1.2996 +"command that lets you specify a changeset ID or revision number accepts both "
  1.2997 +"<option role=\"hg-opt-log\">-r</option> and <option role=\"hg-opt-log\">--"
  1.2998 +"rev</option> arguments."
  1.2999 +msgstr ""
  1.3000 +
  1.3001 +#. type: Content of: <book><chapter><sect1><para>
  1.3002 +#: ../en/ch02-tour-basic.xml:402
  1.3003 +msgid ""
  1.3004 +"In the examples throughout this book, I use short options instead of long.  "
  1.3005 +"This just reflects my own preference, so don't read anything significant into "
  1.3006 +"it."
  1.3007 +msgstr ""
  1.3008 +
  1.3009 +#. type: Content of: <book><chapter><sect1><para>
  1.3010 +#: ../en/ch02-tour-basic.xml:406
  1.3011 +msgid ""
  1.3012 +"Most commands that print output of some kind will print more output when "
  1.3013 +"passed a <option role=\"hg-opt-global\">-v</option> (or <option role=\"hg-opt-"
  1.3014 +"global\">--verbose</option>) option, and less when passed <option role=\"hg-"
  1.3015 +"opt-global\">-q</option> (or <option role=\"hg-opt-global\">--quiet</option>)."
  1.3016 +msgstr ""
  1.3017 +
  1.3018 +#. type: Content of: <book><chapter><sect1><title>
  1.3019 +#: ../en/ch02-tour-basic.xml:414
  1.3020 +msgid "Making and reviewing changes"
  1.3021 +msgstr "创建和复审修改"
  1.3022 +
  1.3023 +#. type: Content of: <book><chapter><sect1><para>
  1.3024 +#: ../en/ch02-tour-basic.xml:416
  1.3025 +msgid ""
  1.3026 +"Now that we have a grasp of viewing history in Mercurial, let's take a look "
  1.3027 +"at making some changes and examining them."
  1.3028 +msgstr ""
  1.3029 +
  1.3030 +#. type: Content of: <book><chapter><sect1><para>
  1.3031 +#: ../en/ch02-tour-basic.xml:420
  1.3032 +msgid ""
  1.3033 +"The first thing we'll do is isolate our experiment in a repository of its "
  1.3034 +"own.  We use the <command role=\"hg-cmd\">hg clone</command> command, but we "
  1.3035 +"don't need to clone a copy of the remote repository.  Since we already have a "
  1.3036 +"copy of it locally, we can just clone that instead.  This is much faster than "
  1.3037 +"cloning over the network, and cloning a local repository uses less disk space "
  1.3038 +"in most cases, too."
  1.3039 +msgstr ""
  1.3040 +
  1.3041 +#. type: Content of: <book><chapter><sect1><para>
  1.3042 +#: ../en/ch02-tour-basic.xml:430
  1.3043 +msgid ""
  1.3044 +"As an aside, it's often good practice to keep a <quote>pristine</quote> copy "
  1.3045 +"of a remote repository around, which you can then make temporary clones of to "
  1.3046 +"create sandboxes for each task you want to work on.  This lets you work on "
  1.3047 +"multiple tasks in parallel, each isolated from the others until it's complete "
  1.3048 +"and you're ready to integrate it back.  Because local clones are so cheap, "
  1.3049 +"there's almost no overhead to cloning and destroying repositories whenever "
  1.3050 +"you want."
  1.3051 +msgstr ""
  1.3052 +
  1.3053 +#. type: Content of: <book><chapter><sect1><para>
  1.3054 +#: ../en/ch02-tour-basic.xml:439
  1.3055 +msgid ""
  1.3056 +"In our <filename class=\"directory\">my-hello</filename> repository, we have "
  1.3057 +"a file <filename>hello.c</filename> that contains the classic <quote>hello, "
  1.3058 +"world</quote> program. Let's use the ancient and venerable <command>sed</"
  1.3059 +"command> command to edit this file so that it prints a second line of "
  1.3060 +"output.  (I'm only using <command>sed</command> to do this because it's easy "
  1.3061 +"to write a scripted example this way.  Since you're not under the same "
  1.3062 +"constraint, you probably won't want to use <command>sed</command>; simply use "
  1.3063 +"your preferred text editor to do the same thing.)"
  1.3064 +msgstr ""
  1.3065 +
  1.3066 +#. type: Content of: <book><chapter><sect1><para>
  1.3067 +#: ../en/ch02-tour-basic.xml:452
  1.3068 +msgid ""
  1.3069 +"Mercurial's <command role=\"hg-cmd\">hg status</command> command will tell us "
  1.3070 +"what Mercurial knows about the files in the repository."
  1.3071 +msgstr ""
  1.3072 +
  1.3073 +#. type: Content of: <book><chapter><sect1><para>
  1.3074 +#: ../en/ch02-tour-basic.xml:458
  1.3075 +msgid ""
  1.3076 +"The <command role=\"hg-cmd\">hg status</command> command prints no output for "
  1.3077 +"some files, but a line starting with <quote><literal>M</literal></quote> for "
  1.3078 +"<filename>hello.c</filename>.  Unless you tell it to, <command role=\"hg-cmd"
  1.3079 +"\">hg status</command> will not print any output for files that have not been "
  1.3080 +"modified."
  1.3081 +msgstr ""
  1.3082 +
  1.3083 +#. type: Content of: <book><chapter><sect1><para>
  1.3084 +#: ../en/ch02-tour-basic.xml:465
  1.3085 +msgid ""
  1.3086 +"The <quote><literal>M</literal></quote> indicates that Mercurial has noticed "
  1.3087 +"that we modified <filename>hello.c</filename>.  We didn't need to "
  1.3088 +"<emphasis>inform</emphasis> Mercurial that we were going to modify the file "
  1.3089 +"before we started, or that we had modified the file after we were done; it "
  1.3090 +"was able to figure this out itself."
  1.3091 +msgstr ""
  1.3092 +
  1.3093 +#. type: Content of: <book><chapter><sect1><para>
  1.3094 +#: ../en/ch02-tour-basic.xml:473
  1.3095 +msgid ""
  1.3096 +"It's a little bit helpful to know that we've modified <filename>hello.c</"
  1.3097 +"filename>, but we might prefer to know exactly <emphasis>what</emphasis> "
  1.3098 +"changes we've made to it.  To do this, we use the <command role=\"hg-cmd\">hg "
  1.3099 +"diff</command> command."
  1.3100 +msgstr ""
  1.3101 +
  1.3102 +#. type: Content of: <book><chapter><sect1><title>
  1.3103 +#: ../en/ch02-tour-basic.xml:483
  1.3104 +msgid "Recording changes in a new changeset"
  1.3105 +msgstr "在新修改集中记录修改"
  1.3106 +
  1.3107 +#. type: Content of: <book><chapter><sect1><para>
  1.3108 +#: ../en/ch02-tour-basic.xml:485
  1.3109 +msgid ""
  1.3110 +"We can modify files, build and test our changes, and use <command role=\"hg-"
  1.3111 +"cmd\">hg status</command> and <command role=\"hg-cmd\">hg diff</command> to "
  1.3112 +"review our changes, until we're satisfied with what we've done and arrive at "
  1.3113 +"a natural stopping point where we want to record our work in a new changeset."
  1.3114 +msgstr ""
  1.3115 +
  1.3116 +#. type: Content of: <book><chapter><sect1><para>
  1.3117 +#: ../en/ch02-tour-basic.xml:492
  1.3118 +msgid ""
  1.3119 +"The <command role=\"hg-cmd\">hg commit</command> command lets us create a new "
  1.3120 +"changeset; we'll usually refer to this as <quote>making a commit</quote> or "
  1.3121 +"<quote>committing</quote>."
  1.3122 +msgstr ""
  1.3123 +
  1.3124 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3125 +#: ../en/ch02-tour-basic.xml:498
  1.3126 +msgid "Setting up a username"
  1.3127 +msgstr "配置用户名称"
  1.3128 +
  1.3129 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3130 +#: ../en/ch02-tour-basic.xml:500
  1.3131 +msgid ""
  1.3132 +"When you try to run <command role=\"hg-cmd\">hg commit</command> for the "
  1.3133 +"first time, it is not guaranteed to succeed.  Mercurial records your name and "
  1.3134 +"address with each change that you commit, so that you and others will later "
  1.3135 +"be able to tell who made each change.  Mercurial tries to automatically "
  1.3136 +"figure out a sensible username to commit the change with.  It will attempt "
  1.3137 +"each of the following methods, in order:"
  1.3138 +msgstr ""
  1.3139 +
  1.3140 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.3141 +#: ../en/ch02-tour-basic.xml:509
  1.3142 +msgid ""
  1.3143 +"If you specify a <option role=\"hg-opt-commit\">-u</option> option to the "
  1.3144 +"<command role=\"hg-cmd\">hg commit</command> command on the command line, "
  1.3145 +"followed by a username, this is always given the highest precedence."
  1.3146 +msgstr ""
  1.3147 +
  1.3148 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.3149 +#: ../en/ch02-tour-basic.xml:514
  1.3150 +msgid ""
  1.3151 +"If you have set the <envar>HGUSER</envar> environment variable, this is "
  1.3152 +"checked next."
  1.3153 +msgstr ""
  1.3154 +
  1.3155 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.3156 +#: ../en/ch02-tour-basic.xml:517
  1.3157 +msgid ""
  1.3158 +"If you create a file in your home directory called <filename role=\"special"
  1.3159 +"\">.hgrc</filename>, with a <envar role=\"rc-item-ui\">username</envar> "
  1.3160 +"entry, that will be used next.  To see what the contents of this file should "
  1.3161 +"look like, refer to section <xref linkend=\"sec.tour-basic.username\"/> below."
  1.3162 +msgstr ""
  1.3163 +
  1.3164 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.3165 +#: ../en/ch02-tour-basic.xml:524
  1.3166 +msgid ""
  1.3167 +"If you have set the <envar>EMAIL</envar> environment variable, this will be "
  1.3168 +"used next."
  1.3169 +msgstr ""
  1.3170 +
  1.3171 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.3172 +#: ../en/ch02-tour-basic.xml:527
  1.3173 +msgid ""
  1.3174 +"Mercurial will query your system to find out your local user name and host "
  1.3175 +"name, and construct a username from these components. Since this often "
  1.3176 +"results in a username that is not very useful, it will print a warning if it "
  1.3177 +"has to do this."
  1.3178 +msgstr ""
  1.3179 +
  1.3180 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3181 +#: ../en/ch02-tour-basic.xml:534
  1.3182 +msgid ""
  1.3183 +"If all of these mechanisms fail, Mercurial will fail, printing an error "
  1.3184 +"message.  In this case, it will not let you commit until you set up a "
  1.3185 +"username."
  1.3186 +msgstr ""
  1.3187 +
  1.3188 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3189 +#: ../en/ch02-tour-basic.xml:538
  1.3190 +msgid ""
  1.3191 +"You should think of the <envar>HGUSER</envar> environment variable and the "
  1.3192 +"<option role=\"hg-opt-commit\">-u</option> option to the <command role=\"hg-"
  1.3193 +"cmd\">hg commit</command> command as ways to <emphasis>override</emphasis> "
  1.3194 +"Mercurial's default selection of username.  For normal use, the simplest and "
  1.3195 +"most robust way to set a username for yourself is by creating a <filename "
  1.3196 +"role=\"special\">.hgrc</filename> file; see below for details."
  1.3197 +msgstr ""
  1.3198 +
  1.3199 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.3200 +#: ../en/ch02-tour-basic.xml:547
  1.3201 +msgid "Creating a Mercurial configuration file"
  1.3202 +msgstr "创建 Mercurial 的配置文件"
  1.3203 +
  1.3204 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.3205 +#: ../en/ch02-tour-basic.xml:549
  1.3206 +msgid ""
  1.3207 +"To set a user name, use your favourite editor to create a file called "
  1.3208 +"<filename role=\"special\">.hgrc</filename> in your home directory.  "
  1.3209 +"Mercurial will use this file to look up your personalised configuration "
  1.3210 +"settings.  The initial contents of your <filename role=\"special\">.hgrc</"
  1.3211 +"filename> should look like this."
  1.3212 +msgstr ""
  1.3213 +
  1.3214 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.3215 +#: ../en/ch02-tour-basic.xml:560
  1.3216 +msgid ""
  1.3217 +"The <quote><literal>[ui]</literal></quote> line begins a <emphasis>section</"
  1.3218 +"emphasis> of the config file, so you can read the <quote><literal>username "
  1.3219 +"= ...</literal></quote> line as meaning <quote>set the value of the "
  1.3220 +"<literal>username</literal> item in the <literal>ui</literal> section</"
  1.3221 +"quote>. A section continues until a new section begins, or the end of the "
  1.3222 +"file.  Mercurial ignores empty lines and treats any text from "
  1.3223 +"<quote><literal>#</literal></quote> to the end of a line as a comment."
  1.3224 +msgstr ""
  1.3225 +
  1.3226 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.3227 +#: ../en/ch02-tour-basic.xml:573
  1.3228 +msgid "Choosing a user name"
  1.3229 +msgstr "选择用户名称"
  1.3230 +
  1.3231 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.3232 +#: ../en/ch02-tour-basic.xml:575
  1.3233 +msgid ""
  1.3234 +"You can use any text you like as the value of the <literal>username</literal> "
  1.3235 +"config item, since this information is for reading by other people, but for "
  1.3236 +"interpreting by Mercurial.  The convention that most people follow is to use "
  1.3237 +"their name and email address, as in the example above."
  1.3238 +msgstr ""
  1.3239 +
  1.3240 +#. type: Content of: <book><chapter><sect1><sect2><sect3><note><para>
  1.3241 +#: ../en/ch02-tour-basic.xml:582
  1.3242 +msgid ""
  1.3243 +"Mercurial's built-in web server obfuscates email addresses, to make it more "
  1.3244 +"difficult for the email harvesting tools that spammers use. This reduces the "
  1.3245 +"likelihood that you'll start receiving more junk email if you publish a "
  1.3246 +"Mercurial repository on the web."
  1.3247 +msgstr ""
  1.3248 +
  1.3249 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3250 +#: ../en/ch02-tour-basic.xml:592
  1.3251 +msgid "Writing a commit message"
  1.3252 +msgstr "写提交日志"
  1.3253 +
  1.3254 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3255 +#: ../en/ch02-tour-basic.xml:594
  1.3256 +msgid ""
  1.3257 +"When we commit a change, Mercurial drops us into a text editor, to enter a "
  1.3258 +"message that will describe the modifications we've made in this changeset.  "
  1.3259 +"This is called the <emphasis>commit message</emphasis>.  It will be a record "
  1.3260 +"for readers of what we did and why, and it will be printed by <command role="
  1.3261 +"\"hg-cmd\">hg log</command> after we've finished committing."
  1.3262 +msgstr ""
  1.3263 +
  1.3264 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3265 +#: ../en/ch02-tour-basic.xml:604
  1.3266 +msgid ""
  1.3267 +"The editor that the <command role=\"hg-cmd\">hg commit</command> command "
  1.3268 +"drops us into will contain an empty line, followed by a number of lines "
  1.3269 +"starting with <quote><literal>HG:</literal></quote>."
  1.3270 +msgstr ""
  1.3271 +
  1.3272 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3273 +#: ../en/ch02-tour-basic.xml:611
  1.3274 +msgid ""
  1.3275 +"Mercurial ignores the lines that start with <quote><literal>HG:</literal></"
  1.3276 +"quote>; it uses them only to tell us which files it's recording changes to.  "
  1.3277 +"Modifying or deleting these lines has no effect."
  1.3278 +msgstr ""
  1.3279 +
  1.3280 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3281 +#: ../en/ch02-tour-basic.xml:617
  1.3282 +msgid "Writing a good commit message"
  1.3283 +msgstr "写好提交日志"
  1.3284 +
  1.3285 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3286 +#: ../en/ch02-tour-basic.xml:619
  1.3287 +msgid ""
  1.3288 +"Since <command role=\"hg-cmd\">hg log</command> only prints the first line of "
  1.3289 +"a commit message by default, it's best to write a commit message whose first "
  1.3290 +"line stands alone.  Here's a real example of a commit message that "
  1.3291 +"<emphasis>doesn't</emphasis> follow this guideline, and hence has a summary "
  1.3292 +"that is not readable."
  1.3293 +msgstr ""
  1.3294 +
  1.3295 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3296 +#: ../en/ch02-tour-basic.xml:633
  1.3297 +msgid ""
  1.3298 +"As far as the remainder of the contents of the commit message are concerned, "
  1.3299 +"there are no hard-and-fast rules.  Mercurial itself doesn't interpret or care "
  1.3300 +"about the contents of the commit message, though your project may have "
  1.3301 +"policies that dictate a certain kind of formatting."
  1.3302 +msgstr ""
  1.3303 +
  1.3304 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3305 +#: ../en/ch02-tour-basic.xml:639
  1.3306 +msgid ""
  1.3307 +"My personal preference is for short, but informative, commit messages that "
  1.3308 +"tell me something that I can't figure out with a quick glance at the output "
  1.3309 +"of <command role=\"hg-cmd\">hg log --patch</command>."
  1.3310 +msgstr ""
  1.3311 +
  1.3312 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3313 +#: ../en/ch02-tour-basic.xml:646
  1.3314 +msgid "Aborting a commit"
  1.3315 +msgstr "终止提交"
  1.3316 +
  1.3317 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3318 +#: ../en/ch02-tour-basic.xml:648
  1.3319 +msgid ""
  1.3320 +"If you decide that you don't want to commit while in the middle of editing a "
  1.3321 +"commit message, simply exit from your editor without saving the file that "
  1.3322 +"it's editing.  This will cause nothing to happen to either the repository or "
  1.3323 +"the working directory."
  1.3324 +msgstr ""
  1.3325 +
  1.3326 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3327 +#: ../en/ch02-tour-basic.xml:653
  1.3328 +msgid ""
  1.3329 +"If we run the <command role=\"hg-cmd\">hg commit</command> command without "
  1.3330 +"any arguments, it records all of the changes we've made, as reported by "
  1.3331 +"<command role=\"hg-cmd\">hg status</command> and <command role=\"hg-cmd\">hg "
  1.3332 +"diff</command>."
  1.3333 +msgstr ""
  1.3334 +
  1.3335 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3336 +#: ../en/ch02-tour-basic.xml:660
  1.3337 +msgid "Admiring our new handiwork"
  1.3338 +msgstr "欣赏我们的新手艺"
  1.3339 +
  1.3340 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3341 +#: ../en/ch02-tour-basic.xml:662
  1.3342 +msgid ""
  1.3343 +"Once we've finished the commit, we can use the <command role=\"hg-cmd\">hg "
  1.3344 +"tip</command> command to display the changeset we just created.  This command "
  1.3345 +"produces output that is identical to <command role=\"hg-cmd\">hg log</"
  1.3346 +"command>, but it only displays the newest revision in the repository."
  1.3347 +msgstr ""
  1.3348 +
  1.3349 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3350 +#: ../en/ch02-tour-basic.xml:671
  1.3351 +msgid ""
  1.3352 +"We refer to the newest revision in the repository as the tip revision, or "
  1.3353 +"simply the tip."
  1.3354 +msgstr ""
  1.3355 +
  1.3356 +#. type: Content of: <book><chapter><sect1><title>
  1.3357 +#: ../en/ch02-tour-basic.xml:678
  1.3358 +msgid "Sharing changes"
  1.3359 +msgstr "共享修改"
  1.3360 +
  1.3361 +#. type: Content of: <book><chapter><sect1><para>
  1.3362 +#: ../en/ch02-tour-basic.xml:680
  1.3363 +msgid ""
  1.3364 +"We mentioned earlier that repositories in Mercurial are self-contained.  This "
  1.3365 +"means that the changeset we just created exists only in our <filename class="
  1.3366 +"\"directory\">my-hello</filename> repository.  Let's look at a few ways that "
  1.3367 +"we can propagate this change into other repositories."
  1.3368 +msgstr ""
  1.3369 +
  1.3370 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3371 +#: ../en/ch02-tour-basic.xml:688
  1.3372 +msgid "Pulling changes from another repository"
  1.3373 +msgstr "从其它版本库取得修改"
  1.3374 +
  1.3375 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3376 +#: ../en/ch02-tour-basic.xml:689
  1.3377 +msgid ""
  1.3378 +"To get started, let's clone our original <filename class=\"directory\">hello</"
  1.3379 +"filename> repository, which does not contain the change we just committed.  "
  1.3380 +"We'll call our temporary repository <filename class=\"directory\">hello-pull</"
  1.3381 +"filename>."
  1.3382 +msgstr ""
  1.3383 +
  1.3384 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3385 +#: ../en/ch02-tour-basic.xml:697
  1.3386 +msgid ""
  1.3387 +"We'll use the <command role=\"hg-cmd\">hg pull</command> command to bring "
  1.3388 +"changes from <filename class=\"directory\">my-hello</filename> into <filename "
  1.3389 +"class=\"directory\">hello-pull</filename>.  However, blindly pulling unknown "
  1.3390 +"changes into a repository is a somewhat scary prospect.  Mercurial provides "
  1.3391 +"the <command role=\"hg-cmd\">hg incoming</command> command to tell us what "
  1.3392 +"changes the <command role=\"hg-cmd\">hg pull</command> command "
  1.3393 +"<emphasis>would</emphasis> pull into the repository, without actually pulling "
  1.3394 +"the changes in."
  1.3395 +msgstr ""
  1.3396 +
  1.3397 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3398 +#: ../en/ch02-tour-basic.xml:710
  1.3399 +msgid ""
  1.3400 +"(Of course, someone could cause more changesets to appear in the repository "
  1.3401 +"that we ran <command role=\"hg-cmd\">hg incoming</command> in, before we get "
  1.3402 +"a chance to <command role=\"hg-cmd\">hg pull</command> the changes, so that "
  1.3403 +"we could end up pulling changes that we didn't expect.)"
  1.3404 +msgstr ""
  1.3405 +
  1.3406 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3407 +#: ../en/ch02-tour-basic.xml:717
  1.3408 +msgid ""
  1.3409 +"Bringing changes into a repository is a simple matter of running the <command "
  1.3410 +"role=\"hg-cmd\">hg pull</command> command, and telling it which repository to "
  1.3411 +"pull from."
  1.3412 +msgstr ""
  1.3413 +
  1.3414 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3415 +#: ../en/ch02-tour-basic.xml:724
  1.3416 +msgid ""
  1.3417 +"As you can see from the before-and-after output of <command role=\"hg-cmd"
  1.3418 +"\">hg tip</command>, we have successfully pulled changes into our "
  1.3419 +"repository.  There remains one step before we can see these changes in the "
  1.3420 +"working directory."
  1.3421 +msgstr ""
  1.3422 +
  1.3423 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3424 +#: ../en/ch02-tour-basic.xml:732
  1.3425 +msgid "Updating the working directory"
  1.3426 +msgstr "更新工作目录"
  1.3427 +
  1.3428 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3429 +#: ../en/ch02-tour-basic.xml:734
  1.3430 +msgid ""
  1.3431 +"We have so far glossed over the relationship between a repository and its "
  1.3432 +"working directory.  The <command role=\"hg-cmd\">hg pull</command> command "
  1.3433 +"that we ran in section <xref linkend=\"sec.tour.pull\"/> brought changes into "
  1.3434 +"the repository, but if we check, there's no sign of those changes in the "
  1.3435 +"working directory.  This is because <command role=\"hg-cmd\">hg pull</"
  1.3436 +"command> does not (by default) touch the working directory.  Instead, we use "
  1.3437 +"the <command role=\"hg-cmd\">hg update</command> command to do this."
  1.3438 +msgstr ""
  1.3439 +
  1.3440 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3441 +#: ../en/ch02-tour-basic.xml:746
  1.3442 +msgid ""
  1.3443 +"It might seem a bit strange that <command role=\"hg-cmd\">hg pull</command> "
  1.3444 +"doesn't update the working directory automatically.  There's actually a good "
  1.3445 +"reason for this: you can use <command role=\"hg-cmd\">hg update</command> to "
  1.3446 +"update the working directory to the state it was in at <emphasis>any "
  1.3447 +"revision</emphasis> in the history of the repository.  If you had the working "
  1.3448 +"directory updated to an old revision---to hunt down the origin of a bug, "
  1.3449 +"say---and ran a <command role=\"hg-cmd\">hg pull</command> which "
  1.3450 +"automatically updated the working directory to a new revision, you might not "
  1.3451 +"be terribly happy."
  1.3452 +msgstr ""
  1.3453 +
  1.3454 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3455 +#: ../en/ch02-tour-basic.xml:757
  1.3456 +msgid ""
  1.3457 +"However, since pull-then-update is such a common thing to do, Mercurial lets "
  1.3458 +"you combine the two by passing the <option role=\"hg-opt-pull\">-u</option> "
  1.3459 +"option to <command role=\"hg-cmd\">hg pull</command>."
  1.3460 +msgstr ""
  1.3461 +
  1.3462 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3463 +#: ../en/ch02-tour-basic.xml:762
  1.3464 +msgid ""
  1.3465 +"If you look back at the output of <command role=\"hg-cmd\">hg pull</command> "
  1.3466 +"in section <xref linkend=\"sec.tour.pull\"/> when we ran it without <option "
  1.3467 +"role=\"hg-opt-pull\">-u</option>, you can see that it printed a helpful "
  1.3468 +"reminder that we'd have to take an explicit step to update the working "
  1.3469 +"directory:"
  1.3470 +msgstr ""
  1.3471 +
  1.3472 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3473 +#: ../en/ch02-tour-basic.xml:771
  1.3474 +msgid ""
  1.3475 +"To find out what revision the working directory is at, use the <command role="
  1.3476 +"\"hg-cmd\">hg parents</command> command."
  1.3477 +msgstr ""
  1.3478 +
  1.3479 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3480 +#: ../en/ch02-tour-basic.xml:777
  1.3481 +msgid ""
  1.3482 +"If you look back at figure <xref linkend=\"fig.tour-basic.history\"/>, you'll "
  1.3483 +"see arrows connecting each changeset.  The node that the arrow leads "
  1.3484 +"<emphasis>from</emphasis> in each case is a parent, and the node that the "
  1.3485 +"arrow leads <emphasis>to</emphasis> is its child.  The working directory has "
  1.3486 +"a parent in just the same way; this is the changeset that the working "
  1.3487 +"directory currently contains."
  1.3488 +msgstr ""
  1.3489 +
  1.3490 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3491 +#: ../en/ch02-tour-basic.xml:786
  1.3492 +msgid ""
  1.3493 +"To update the working directory to a particular revision, give a revision "
  1.3494 +"number or changeset ID to the <command role=\"hg-cmd\">hg update</command> "
  1.3495 +"command."
  1.3496 +msgstr ""
  1.3497 +
  1.3498 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3499 +#: ../en/ch02-tour-basic.xml:793
  1.3500 +msgid ""
  1.3501 +"If you omit an explicit revision, <command role=\"hg-cmd\">hg update</"
  1.3502 +"command> will update to the tip revision, as shown by the second call to "
  1.3503 +"<command role=\"hg-cmd\">hg update</command> in the example above."
  1.3504 +msgstr ""
  1.3505 +
  1.3506 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3507 +#: ../en/ch02-tour-basic.xml:801
  1.3508 +msgid "Pushing changes to another repository"
  1.3509 +msgstr "发布修改到其它版本库"
  1.3510 +
  1.3511 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3512 +#: ../en/ch02-tour-basic.xml:803
  1.3513 +msgid ""
  1.3514 +"Mercurial lets us push changes to another repository, from the repository "
  1.3515 +"we're currently visiting.  As with the example of <command role=\"hg-cmd\">hg "
  1.3516 +"pull</command> above, we'll create a temporary repository to push our changes "
  1.3517 +"into."
  1.3518 +msgstr ""
  1.3519 +
  1.3520 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3521 +#: ../en/ch02-tour-basic.xml:811
  1.3522 +msgid ""
  1.3523 +"The <command role=\"hg-cmd\">hg outgoing</command> command tells us what "
  1.3524 +"changes would be pushed into another repository."
  1.3525 +msgstr ""
  1.3526 +
  1.3527 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3528 +#: ../en/ch02-tour-basic.xml:817
  1.3529 +msgid ""
  1.3530 +"And the <command role=\"hg-cmd\">hg push</command> command does the actual "
  1.3531 +"push."
  1.3532 +msgstr ""
  1.3533 +
  1.3534 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3535 +#: ../en/ch02-tour-basic.xml:823
  1.3536 +msgid ""
  1.3537 +"As with <command role=\"hg-cmd\">hg pull</command>, the <command role=\"hg-cmd"
  1.3538 +"\">hg push</command> command does not update the working directory in the "
  1.3539 +"repository that it's pushing changes into. (Unlike <command role=\"hg-cmd"
  1.3540 +"\">hg pull</command>, <command role=\"hg-cmd\">hg push</command> does not "
  1.3541 +"provide a <literal>-u</literal> option that updates the other repository's "
  1.3542 +"working directory.)"
  1.3543 +msgstr ""
  1.3544 +
  1.3545 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3546 +#: ../en/ch02-tour-basic.xml:832
  1.3547 +msgid ""
  1.3548 +"What happens if we try to pull or push changes and the receiving repository "
  1.3549 +"already has those changes? Nothing too exciting."
  1.3550 +msgstr ""
  1.3551 +
  1.3552 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3553 +#: ../en/ch02-tour-basic.xml:839
  1.3554 +msgid "Sharing changes over a network"
  1.3555 +msgstr "通过网络共享修改"
  1.3556 +
  1.3557 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3558 +#: ../en/ch02-tour-basic.xml:841
  1.3559 +msgid ""
  1.3560 +"The commands we have covered in the previous few sections are not limited to "
  1.3561 +"working with local repositories.  Each works in exactly the same fashion over "
  1.3562 +"a network connection; simply pass in a URL instead of a local path."
  1.3563 +msgstr ""
  1.3564 +
  1.3565 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3566 +#: ../en/ch02-tour-basic.xml:849
  1.3567 +msgid ""
  1.3568 +"In this example, we can see what changes we could push to the remote "
  1.3569 +"repository, but the repository is understandably not set up to let anonymous "
  1.3570 +"users push to it."
  1.3571 +msgstr ""
  1.3572 +
  1.3573 +#. type: Content of: <book><chapter><title>
  1.3574 +#: ../en/ch03-tour-merge.xml:5
  1.3575 +msgid "A tour of Mercurial: merging work"
  1.3576 +msgstr "Mercurial 教程: 合并工作"
  1.3577 +
  1.3578 +#. type: Content of: <book><chapter><para>
  1.3579 +#: ../en/ch03-tour-merge.xml:7
  1.3580 +msgid ""
  1.3581 +"We've now covered cloning a repository, making changes in a repository, and "
  1.3582 +"pulling or pushing changes from one repository into another.  Our next step "
  1.3583 +"is <emphasis>merging</emphasis> changes from separate repositories."
  1.3584 +msgstr ""
  1.3585 +
  1.3586 +#. type: Content of: <book><chapter><sect1><title>
  1.3587 +#: ../en/ch03-tour-merge.xml:13
  1.3588 +msgid "Merging streams of work"
  1.3589 +msgstr "合并的流程"
  1.3590 +
  1.3591 +#. type: Content of: <book><chapter><sect1><para>
  1.3592 +#: ../en/ch03-tour-merge.xml:15
  1.3593 +msgid ""
  1.3594 +"Merging is a fundamental part of working with a distributed revision control "
  1.3595 +"tool."
  1.3596 +msgstr ""
  1.3597 +
  1.3598 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.3599 +#: ../en/ch03-tour-merge.xml:18
  1.3600 +msgid ""
  1.3601 +"Alice and Bob each have a personal copy of a repository for a project they're "
  1.3602 +"collaborating on.  Alice fixes a bug in her repository; Bob adds a new "
  1.3603 +"feature in his.  They want the shared repository to contain both the bug fix "
  1.3604 +"and the new feature."
  1.3605 +msgstr ""
  1.3606 +
  1.3607 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.3608 +#: ../en/ch03-tour-merge.xml:24
  1.3609 +msgid ""
  1.3610 +"I frequently work on several different tasks for a single project at once, "
  1.3611 +"each safely isolated in its own repository. Working this way means that I "
  1.3612 +"often need to merge one piece of my own work with another."
  1.3613 +msgstr ""
  1.3614 +
  1.3615 +#. type: Content of: <book><chapter><sect1><para>
  1.3616 +#: ../en/ch03-tour-merge.xml:30
  1.3617 +msgid ""
  1.3618 +"Because merging is such a common thing to need to do, Mercurial makes it "
  1.3619 +"easy.  Let's walk through the process.  We'll begin by cloning yet another "
  1.3620 +"repository (see how often they spring up?) and making a change in it."
  1.3621 +msgstr ""
  1.3622 +
  1.3623 +#. type: Content of: <book><chapter><sect1><para>
  1.3624 +#: ../en/ch03-tour-merge.xml:37
  1.3625 +msgid ""
  1.3626 +"We should now have two copies of <filename>hello.c</filename> with different "
  1.3627 +"contents.  The histories of the two repositories have also diverged, as "
  1.3628 +"illustrated in figure <xref linkend=\"fig.tour-merge.sep-repos\"/>."
  1.3629 +msgstr ""
  1.3630 +
  1.3631 +#. type: Content of: <book><chapter><sect1><informalfigure><mediaobject>
  1.3632 +#: ../en/ch03-tour-merge.xml:47
  1.3633 +msgid ""
  1.3634 +"<imageobject><imagedata fileref=\"images/tour-merge-sep-repos.png\"/></"
  1.3635 +"imageobject>"
  1.3636 +msgstr ""
  1.3637 +
  1.3638 +#. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para>
  1.3639 +#: ../en/ch03-tour-merge.xml:49
  1.3640 +msgid ""
  1.3641 +"Divergent recent histories of the <filename class=\"directory\">my-hello</"
  1.3642 +"filename> and <filename class=\"directory\">my-new-hello</filename> "
  1.3643 +"repositories"
  1.3644 +msgstr ""
  1.3645 +
  1.3646 +#. type: Content of: <book><chapter><sect1><para>
  1.3647 +#: ../en/ch03-tour-merge.xml:56
  1.3648 +msgid ""
  1.3649 +"We already know that pulling changes from our <filename class=\"directory"
  1.3650 +"\">my-hello</filename> repository will have no effect on the working "
  1.3651 +"directory."
  1.3652 +msgstr ""
  1.3653 +
  1.3654 +#. type: Content of: <book><chapter><sect1><para>
  1.3655 +#: ../en/ch03-tour-merge.xml:62
  1.3656 +msgid ""
  1.3657 +"However, the <command role=\"hg-cmd\">hg pull</command> command says "
  1.3658 +"something about <quote>heads</quote>."
  1.3659 +msgstr ""
  1.3660 +
  1.3661 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3662 +#: ../en/ch03-tour-merge.xml:66
  1.3663 +msgid "Head changesets"
  1.3664 +msgstr "顶点改变集"
  1.3665 +
  1.3666 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3667 +#: ../en/ch03-tour-merge.xml:68
  1.3668 +msgid ""
  1.3669 +"A head is a change that has no descendants, or children, as they're also "
  1.3670 +"known.  The tip revision is thus a head, because the newest revision in a "
  1.3671 +"repository doesn't have any children, but a repository can contain more than "
  1.3672 +"one head."
  1.3673 +msgstr ""
  1.3674 +
  1.3675 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.3676 +#: ../en/ch03-tour-merge.xml:75
  1.3677 +msgid ""
  1.3678 +"<imageobject><imagedata fileref=\"images/tour-merge-pull.png\"/></imageobject>"
  1.3679 +msgstr ""
  1.3680 +
  1.3681 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.3682 +#: ../en/ch03-tour-merge.xml:78
  1.3683 +msgid ""
  1.3684 +"Repository contents after pulling from <filename class=\"directory\">my-"
  1.3685 +"hello</filename> into <filename class=\"directory\">my-new-hello</filename>"
  1.3686 +msgstr ""
  1.3687 +
  1.3688 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3689 +#: ../en/ch03-tour-merge.xml:85
  1.3690 +msgid ""
  1.3691 +"In figure <xref linkend=\"fig.tour-merge.pull\"/>, you can see the effect of "
  1.3692 +"the pull from <filename class=\"directory\">my-hello</filename> into "
  1.3693 +"<filename class=\"directory\">my-new-hello</filename>.  The history that was "
  1.3694 +"already present in <filename class=\"directory\">my-new-hello</filename> is "
  1.3695 +"untouched, but a new revision has been added.  By referring to figure <xref "
  1.3696 +"linkend=\"fig.tour-merge.sep-repos\"/>, we can see that the "
  1.3697 +"<emphasis>changeset ID</emphasis> remains the same in the new repository, but "
  1.3698 +"the <emphasis>revision number</emphasis> has changed.  (This, incidentally, "
  1.3699 +"is a fine example of why it's not safe to use revision numbers when "
  1.3700 +"discussing changesets.)  We can view the heads in a repository using the "
  1.3701 +"<command role=\"hg-cmd\">hg heads</command> command."
  1.3702 +msgstr ""
  1.3703 +
  1.3704 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3705 +#: ../en/ch03-tour-merge.xml:104
  1.3706 +msgid "Performing the merge"
  1.3707 +msgstr "执行合并"
  1.3708 +
  1.3709 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3710 +#: ../en/ch03-tour-merge.xml:106
  1.3711 +msgid ""
  1.3712 +"What happens if we try to use the normal <command role=\"hg-cmd\">hg update</"
  1.3713 +"command> command to update to the new tip?"
  1.3714 +msgstr ""
  1.3715 +
  1.3716 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3717 +#: ../en/ch03-tour-merge.xml:112
  1.3718 +msgid ""
  1.3719 +"Mercurial is telling us that the <command role=\"hg-cmd\">hg update</command> "
  1.3720 +"command won't do a merge; it won't update the working directory when it "
  1.3721 +"thinks we might be wanting to do a merge, unless we force it to do so.  "
  1.3722 +"Instead, we use the <command role=\"hg-cmd\">hg merge</command> command to "
  1.3723 +"merge the two heads."
  1.3724 +msgstr ""
  1.3725 +
  1.3726 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.3727 +#: ../en/ch03-tour-merge.xml:123
  1.3728 +msgid ""
  1.3729 +"<imageobject><imagedata fileref=\"images/tour-merge-merge.png\"/></"
  1.3730 +"imageobject>"
  1.3731 +msgstr ""
  1.3732 +
  1.3733 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.3734 +#: ../en/ch03-tour-merge.xml:126
  1.3735 +msgid "Working directory and repository during merge, and following commit"
  1.3736 +msgstr ""
  1.3737 +
  1.3738 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3739 +#: ../en/ch03-tour-merge.xml:131
  1.3740 +msgid ""
  1.3741 +"This updates the working directory so that it contains changes from "
  1.3742 +"<emphasis>both</emphasis> heads, which is reflected in both the output of "
  1.3743 +"<command role=\"hg-cmd\">hg parents</command> and the contents of "
  1.3744 +"<filename>hello.c</filename>."
  1.3745 +msgstr ""
  1.3746 +
  1.3747 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3748 +#: ../en/ch03-tour-merge.xml:141
  1.3749 +msgid "Committing the results of the merge"
  1.3750 +msgstr "提交合并结果"
  1.3751 +
  1.3752 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3753 +#: ../en/ch03-tour-merge.xml:143
  1.3754 +msgid ""
  1.3755 +"Whenever we've done a merge, <command role=\"hg-cmd\">hg parents</command> "
  1.3756 +"will display two parents until we <command role=\"hg-cmd\">hg commit</"
  1.3757 +"command> the results of the merge."
  1.3758 +msgstr ""
  1.3759 +
  1.3760 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3761 +#: ../en/ch03-tour-merge.xml:150
  1.3762 +msgid ""
  1.3763 +"We now have a new tip revision; notice that it has <emphasis>both</emphasis> "
  1.3764 +"of our former heads as its parents.  These are the same revisions that were "
  1.3765 +"previously displayed by <command role=\"hg-cmd\">hg parents</command>."
  1.3766 +msgstr ""
  1.3767 +
  1.3768 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3769 +#: ../en/ch03-tour-merge.xml:157
  1.3770 +msgid ""
  1.3771 +"In figure <xref linkend=\"fig.tour-merge.merge\"/>, you can see a "
  1.3772 +"representation of what happens to the working directory during the merge, and "
  1.3773 +"how this affects the repository when the commit happens.  During the merge, "
  1.3774 +"the working directory has two parent changesets, and these become the parents "
  1.3775 +"of the new changeset."
  1.3776 +msgstr ""
  1.3777 +
  1.3778 +#. type: Content of: <book><chapter><sect1><title>
  1.3779 +#: ../en/ch03-tour-merge.xml:168
  1.3780 +msgid "Merging conflicting changes"
  1.3781 +msgstr "合并有冲突的改变"
  1.3782 +
  1.3783 +#. type: Content of: <book><chapter><sect1><para>
  1.3784 +#: ../en/ch03-tour-merge.xml:170
  1.3785 +msgid ""
  1.3786 +"Most merges are simple affairs, but sometimes you'll find yourself merging "
  1.3787 +"changes where each modifies the same portions of the same files.  Unless both "
  1.3788 +"modifications are identical, this results in a <emphasis>conflict</emphasis>, "
  1.3789 +"where you have to decide how to reconcile the different changes into "
  1.3790 +"something coherent."
  1.3791 +msgstr ""
  1.3792 +
  1.3793 +#. type: Content of: <book><chapter><sect1><informalfigure><mediaobject>
  1.3794 +#: ../en/ch03-tour-merge.xml:180
  1.3795 +msgid ""
  1.3796 +"<imageobject><imagedata fileref=\"images/tour-merge-conflict.png\"/></"
  1.3797 +"imageobject>"
  1.3798 +msgstr ""
  1.3799 +
  1.3800 +#. type: Content of: <book><chapter><sect1><informalfigure><mediaobject><caption><para>
  1.3801 +#: ../en/ch03-tour-merge.xml:182
  1.3802 +msgid "Conflicting changes to a document"
  1.3803 +msgstr ""
  1.3804 +
  1.3805 +#. type: Content of: <book><chapter><sect1><para>
  1.3806 +#: ../en/ch03-tour-merge.xml:186
  1.3807 +msgid ""
  1.3808 +"Figure <xref linkend=\"fig.tour-merge.conflict\"/> illustrates an instance of "
  1.3809 +"two conflicting changes to a document.  We started with a single version of "
  1.3810 +"the file; then we made some changes; while someone else made different "
  1.3811 +"changes to the same text.  Our task in resolving the conflicting changes is "
  1.3812 +"to decide what the file should look like."
  1.3813 +msgstr ""
  1.3814 +
  1.3815 +#. type: Content of: <book><chapter><sect1><para>
  1.3816 +#: ../en/ch03-tour-merge.xml:193
  1.3817 +msgid ""
  1.3818 +"Mercurial doesn't have a built-in facility for handling conflicts. Instead, "
  1.3819 +"it runs an external program called <command>hgmerge</command>.  This is a "
  1.3820 +"shell script that is bundled with Mercurial; you can change it to behave "
  1.3821 +"however you please.  What it does by default is try to find one of several "
  1.3822 +"different merging tools that are likely to be installed on your system.  It "
  1.3823 +"first tries a few fully automatic merging tools; if these don't succeed "
  1.3824 +"(because the resolution process requires human guidance) or aren't present, "
  1.3825 +"the script tries a few different graphical merging tools."
  1.3826 +msgstr ""
  1.3827 +
  1.3828 +#. type: Content of: <book><chapter><sect1><para>
  1.3829 +#: ../en/ch03-tour-merge.xml:204
  1.3830 +msgid ""
  1.3831 +"It's also possible to get Mercurial to run another program or script instead "
  1.3832 +"of <command>hgmerge</command>, by setting the <envar>HGMERGE</envar> "
  1.3833 +"environment variable to the name of your preferred program."
  1.3834 +msgstr ""
  1.3835 +
  1.3836 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3837 +#: ../en/ch03-tour-merge.xml:210
  1.3838 +msgid "Using a graphical merge tool"
  1.3839 +msgstr "使用图形合并工具"
  1.3840 +
  1.3841 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3842 +#: ../en/ch03-tour-merge.xml:212
  1.3843 +msgid ""
  1.3844 +"My preferred graphical merge tool is <command>kdiff3</command>, which I'll "
  1.3845 +"use to describe the features that are common to graphical file merging "
  1.3846 +"tools.  You can see a screenshot of <command>kdiff3</command> in action in "
  1.3847 +"figure <xref linkend=\"fig.tour-merge.kdiff3\"/>.  The kind of merge it is "
  1.3848 +"performing is called a <emphasis>three-way merge</emphasis>, because there "
  1.3849 +"are three different versions of the file of interest to us.  The tool thus "
  1.3850 +"splits the upper portion of the window into three panes:"
  1.3851 +msgstr ""
  1.3852 +
  1.3853 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.3854 +#: ../en/ch03-tour-merge.xml:222
  1.3855 +msgid ""
  1.3856 +"At the left is the <emphasis>base</emphasis> version of the file, i.e. the "
  1.3857 +"most recent version from which the two versions we're trying to merge are "
  1.3858 +"descended."
  1.3859 +msgstr ""
  1.3860 +
  1.3861 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.3862 +#: ../en/ch03-tour-merge.xml:227
  1.3863 +msgid ""
  1.3864 +"In the middle is <quote>our</quote> version of the file, with the contents "
  1.3865 +"that we modified."
  1.3866 +msgstr ""
  1.3867 +
  1.3868 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.3869 +#: ../en/ch03-tour-merge.xml:230
  1.3870 +msgid ""
  1.3871 +"On the right is <quote>their</quote> version of the file, the one that from "
  1.3872 +"the changeset that we're trying to merge with."
  1.3873 +msgstr ""
  1.3874 +
  1.3875 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3876 +#: ../en/ch03-tour-merge.xml:234
  1.3877 +msgid ""
  1.3878 +"In the pane below these is the current <emphasis>result</emphasis> of the "
  1.3879 +"merge. Our task is to replace all of the red text, which indicates unresolved "
  1.3880 +"conflicts, with some sensible merger of the <quote>ours</quote> and "
  1.3881 +"<quote>theirs</quote> versions of the file."
  1.3882 +msgstr ""
  1.3883 +
  1.3884 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3885 +#: ../en/ch03-tour-merge.xml:241
  1.3886 +msgid ""
  1.3887 +"All four of these panes are <emphasis>locked together</emphasis>; if we "
  1.3888 +"scroll vertically or horizontally in any of them, the others are updated to "
  1.3889 +"display the corresponding sections of their respective files."
  1.3890 +msgstr ""
  1.3891 +
  1.3892 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.3893 +#: ../en/ch03-tour-merge.xml:247
  1.3894 +msgid "<imageobject><imagedata fileref=\"images/kdiff3.png\"/></imageobject>"
  1.3895 +msgstr ""
  1.3896 +
  1.3897 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.3898 +#: ../en/ch03-tour-merge.xml:250
  1.3899 +msgid "Using <command>kdiff3</command> to merge versions of a file"
  1.3900 +msgstr ""
  1.3901 +
  1.3902 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3903 +#: ../en/ch03-tour-merge.xml:255
  1.3904 +msgid ""
  1.3905 +"For each conflicting portion of the file, we can choose to resolve the "
  1.3906 +"conflict using some combination of text from the base version, ours, or "
  1.3907 +"theirs.  We can also manually edit the merged file at any time, in case we "
  1.3908 +"need to make further modifications."
  1.3909 +msgstr ""
  1.3910 +
  1.3911 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3912 +#: ../en/ch03-tour-merge.xml:261
  1.3913 +msgid ""
  1.3914 +"There are <emphasis>many</emphasis> file merging tools available, too many to "
  1.3915 +"cover here.  They vary in which platforms they are available for, and in "
  1.3916 +"their particular strengths and weaknesses.  Most are tuned for merging files "
  1.3917 +"containing plain text, while a few are aimed at specialised file formats "
  1.3918 +"(generally XML)."
  1.3919 +msgstr ""
  1.3920 +
  1.3921 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.3922 +#: ../en/ch03-tour-merge.xml:270
  1.3923 +msgid "A worked example"
  1.3924 +msgstr "合并实例"
  1.3925 +
  1.3926 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3927 +#: ../en/ch03-tour-merge.xml:272
  1.3928 +msgid ""
  1.3929 +"In this example, we will reproduce the file modification history of figure "
  1.3930 +"<xref linkend=\"fig.tour-merge.conflict\"/> above.  Let's begin by creating a "
  1.3931 +"repository with a base version of our document."
  1.3932 +msgstr ""
  1.3933 +
  1.3934 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3935 +#: ../en/ch03-tour-merge.xml:279
  1.3936 +msgid "We'll clone the repository and make a change to the file."
  1.3937 +msgstr ""
  1.3938 +
  1.3939 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3940 +#: ../en/ch03-tour-merge.xml:284
  1.3941 +msgid ""
  1.3942 +"And another clone, to simulate someone else making a change to the file. "
  1.3943 +"(This hints at the idea that it's not all that unusual to merge with yourself "
  1.3944 +"when you isolate tasks in separate repositories, and indeed to find and "
  1.3945 +"resolve conflicts while doing so.)"
  1.3946 +msgstr ""
  1.3947 +
  1.3948 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3949 +#: ../en/ch03-tour-merge.xml:292
  1.3950 +msgid ""
  1.3951 +"Having created two different versions of the file, we'll set up an "
  1.3952 +"environment suitable for running our merge."
  1.3953 +msgstr ""
  1.3954 +
  1.3955 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3956 +#: ../en/ch03-tour-merge.xml:298
  1.3957 +msgid ""
  1.3958 +"In this example, I won't use Mercurial's normal <command>hgmerge</command> "
  1.3959 +"program to do the merge, because it would drop my nice automated example-"
  1.3960 +"running tool into a graphical user interface.  Instead, I'll set "
  1.3961 +"<envar>HGMERGE</envar> to tell Mercurial to use the non-interactive "
  1.3962 +"<command>merge</command> command.  This is bundled with many Unix-like "
  1.3963 +"systems. If you're following this example on your computer, don't bother "
  1.3964 +"setting <envar>HGMERGE</envar>."
  1.3965 +msgstr ""
  1.3966 +
  1.3967 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3968 +#: ../en/ch03-tour-merge.xml:308
  1.3969 +msgid "<emphasis role=\"bold\">XXX FIX THIS EXAMPLE.</emphasis>"
  1.3970 +msgstr ""
  1.3971 +
  1.3972 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3973 +#: ../en/ch03-tour-merge.xml:313
  1.3974 +msgid ""
  1.3975 +"Because <command>merge</command> can't resolve the conflicting changes, it "
  1.3976 +"leaves <emphasis>merge markers</emphasis> inside the file that has conflicts, "
  1.3977 +"indicating which lines have conflicts, and whether they came from our version "
  1.3978 +"of the file or theirs."
  1.3979 +msgstr ""
  1.3980 +
  1.3981 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3982 +#: ../en/ch03-tour-merge.xml:319
  1.3983 +msgid ""
  1.3984 +"Mercurial can tell from the way <command>merge</command> exits that it wasn't "
  1.3985 +"able to merge successfully, so it tells us what commands we'll need to run if "
  1.3986 +"we want to redo the merging operation.  This could be useful if, for example, "
  1.3987 +"we were running a graphical merge tool and quit because we were confused or "
  1.3988 +"realised we had made a mistake."
  1.3989 +msgstr ""
  1.3990 +
  1.3991 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.3992 +#: ../en/ch03-tour-merge.xml:326
  1.3993 +msgid ""
  1.3994 +"If automatic or manual merges fail, there's nothing to prevent us from "
  1.3995 +"<quote>fixing up</quote> the affected files ourselves, and committing the "
  1.3996 +"results of our merge:"
  1.3997 +msgstr ""
  1.3998 +
  1.3999 +#. type: Content of: <book><chapter><sect1><title>
  1.4000 +#: ../en/ch03-tour-merge.xml:335
  1.4001 +msgid "Simplifying the pull-merge-commit sequence"
  1.4002 +msgstr "简化拉-合并-提交程序"
  1.4003 +
  1.4004 +#. type: Content of: <book><chapter><sect1><para>
  1.4005 +#: ../en/ch03-tour-merge.xml:337
  1.4006 +msgid ""
  1.4007 +"The process of merging changes as outlined above is straightforward, but "
  1.4008 +"requires running three commands in sequence."
  1.4009 +msgstr ""
  1.4010 +
  1.4011 +#. type: Content of: <book><chapter><sect1><para>
  1.4012 +#: ../en/ch03-tour-merge.xml:343
  1.4013 +msgid ""
  1.4014 +"In the case of the final commit, you also need to enter a commit message, "
  1.4015 +"which is almost always going to be a piece of uninteresting "
  1.4016 +"<quote>boilerplate</quote> text."
  1.4017 +msgstr ""
  1.4018 +
  1.4019 +#. type: Content of: <book><chapter><sect1><para>
  1.4020 +#: ../en/ch03-tour-merge.xml:347
  1.4021 +msgid ""
  1.4022 +"It would be nice to reduce the number of steps needed, if this were "
  1.4023 +"possible.  Indeed, Mercurial is distributed with an extension called <literal "
  1.4024 +"role=\"hg-ext\">fetch</literal> that does just this."
  1.4025 +msgstr ""
  1.4026 +
  1.4027 +#. type: Content of: <book><chapter><sect1><para>
  1.4028 +#: ../en/ch03-tour-merge.xml:352
  1.4029 +msgid ""
  1.4030 +"Mercurial provides a flexible extension mechanism that lets people extend its "
  1.4031 +"functionality, while keeping the core of Mercurial small and easy to deal "
  1.4032 +"with.  Some extensions add new commands that you can use from the command "
  1.4033 +"line, while others work <quote>behind the scenes,</quote> for example adding "
  1.4034 +"capabilities to the server."
  1.4035 +msgstr ""
  1.4036 +
  1.4037 +#. type: Content of: <book><chapter><sect1><para>
  1.4038 +#: ../en/ch03-tour-merge.xml:359
  1.4039 +msgid ""
  1.4040 +"The <literal role=\"hg-ext\">fetch</literal> extension adds a new command "
  1.4041 +"called, not surprisingly, <command role=\"hg-cmd\">hg fetch</command>.  This "
  1.4042 +"extension acts as a combination of <command role=\"hg-cmd\">hg pull</"
  1.4043 +"command>, <command role=\"hg-cmd\">hg update</command> and <command role=\"hg-"
  1.4044 +"cmd\">hg merge</command>.  It begins by pulling changes from another "
  1.4045 +"repository into the current repository.  If it finds that the changes added a "
  1.4046 +"new head to the repository, it begins a merge, then commits the result of the "
  1.4047 +"merge with an automatically-generated commit message.  If no new heads were "
  1.4048 +"added, it updates the working directory to the new tip changeset."
  1.4049 +msgstr ""
  1.4050 +
  1.4051 +#. type: Content of: <book><chapter><sect1><para>
  1.4052 +#: ../en/ch03-tour-merge.xml:372
  1.4053 +msgid ""
  1.4054 +"Enabling the <literal role=\"hg-ext\">fetch</literal> extension is easy.  "
  1.4055 +"Edit your <filename role=\"special\">.hgrc</filename>, and either go to the "
  1.4056 +"<literal role=\"rc-extensions\">extensions</literal> section or create an "
  1.4057 +"<literal role=\"rc-extensions\">extensions</literal> section. Then add a line "
  1.4058 +"that simply reads <quote><literal>fetch </literal></quote>."
  1.4059 +msgstr ""
  1.4060 +
  1.4061 +#. type: Content of: <book><chapter><sect1><para>
  1.4062 +#: ../en/ch03-tour-merge.xml:382
  1.4063 +msgid ""
  1.4064 +"(Normally, on the right-hand side of the <quote><literal>=</literal></quote> "
  1.4065 +"would appear the location of the extension, but since the <literal role=\"hg-"
  1.4066 +"ext\">fetch</literal> extension is in the standard distribution, Mercurial "
  1.4067 +"knows where to search for it.)"
  1.4068 +msgstr ""
  1.4069 +
  1.4070 +#. type: Content of: <book><chapter><title>
  1.4071 +#: ../en/ch04-concepts.xml:5
  1.4072 +msgid "Behind the scenes"
  1.4073 +msgstr "Mercurial 内幕"
  1.4074 +
  1.4075 +#. type: Content of: <book><chapter><para>
  1.4076 +#: ../en/ch04-concepts.xml:7
  1.4077 +msgid ""
  1.4078 +"Unlike many revision control systems, the concepts upon which Mercurial is "
  1.4079 +"built are simple enough that it's easy to understand how the software really "
  1.4080 +"works.  Knowing this certainly isn't necessary, but I find it useful to have "
  1.4081 +"a <quote>mental model</quote> of what's going on."
  1.4082 +msgstr ""
  1.4083 +
  1.4084 +#. type: Content of: <book><chapter><para>
  1.4085 +#: ../en/ch04-concepts.xml:13
  1.4086 +msgid ""
  1.4087 +"This understanding gives me confidence that Mercurial has been carefully "
  1.4088 +"designed to be both <emphasis>safe</emphasis> and <emphasis>efficient</"
  1.4089 +"emphasis>.  And just as importantly, if it's easy for me to retain a good "
  1.4090 +"idea of what the software is doing when I perform a revision control task, "
  1.4091 +"I'm less likely to be surprised by its behaviour."
  1.4092 +msgstr ""
  1.4093 +
  1.4094 +#. type: Content of: <book><chapter><para>
  1.4095 +#: ../en/ch04-concepts.xml:20
  1.4096 +msgid ""
  1.4097 +"In this chapter, we'll initially cover the core concepts behind Mercurial's "
  1.4098 +"design, then continue to discuss some of the interesting details of its "
  1.4099 +"implementation."
  1.4100 +msgstr ""
  1.4101 +
  1.4102 +#. type: Content of: <book><chapter><sect1><title>
  1.4103 +#: ../en/ch04-concepts.xml:25
  1.4104 +msgid "Mercurial's historical record"
  1.4105 +msgstr "Mercurial 的历史记录"
  1.4106 +
  1.4107 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4108 +#: ../en/ch04-concepts.xml:28
  1.4109 +msgid "Tracking the history of a single file"
  1.4110 +msgstr "跟踪单一文件的历史"
  1.4111 +
  1.4112 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4113 +#: ../en/ch04-concepts.xml:30
  1.4114 +msgid ""
  1.4115 +"When Mercurial tracks modifications to a file, it stores the history of that "
  1.4116 +"file in a metadata object called a <emphasis>filelog</emphasis>.  Each entry "
  1.4117 +"in the filelog contains enough information to reconstruct one revision of the "
  1.4118 +"file that is being tracked.  Filelogs are stored as files in the <filename "
  1.4119 +"role=\"special\" class=\"directory\">.hg/store/data</filename> directory.  A "
  1.4120 +"filelog contains two kinds of information: revision data, and an index to "
  1.4121 +"help Mercurial to find a revision efficiently."
  1.4122 +msgstr ""
  1.4123 +
  1.4124 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4125 +#: ../en/ch04-concepts.xml:41
  1.4126 +msgid ""
  1.4127 +"A file that is large, or has a lot of history, has its filelog stored in "
  1.4128 +"separate data (<quote><literal>.d</literal></quote> suffix) and index "
  1.4129 +"(<quote><literal>.i</literal></quote> suffix) files.  For small files without "
  1.4130 +"much history, the revision data and index are combined in a single "
  1.4131 +"<quote><literal>.i</literal></quote> file.  The correspondence between a file "
  1.4132 +"in the working directory and the filelog that tracks its history in the "
  1.4133 +"repository is illustrated in figure <xref linkend=\"fig.concepts.filelog\"/>."
  1.4134 +msgstr ""
  1.4135 +
  1.4136 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4137 +#: ../en/ch04-concepts.xml:53
  1.4138 +msgid "<imageobject><imagedata fileref=\"images/filelog.png\"/></imageobject>"
  1.4139 +msgstr ""
  1.4140 +
  1.4141 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4142 +#: ../en/ch04-concepts.xml:56
  1.4143 +msgid ""
  1.4144 +"Relationships between files in working directory and filelogs in repository"
  1.4145 +msgstr ""
  1.4146 +
  1.4147 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4148 +#: ../en/ch04-concepts.xml:63
  1.4149 +msgid "Managing tracked files"
  1.4150 +msgstr "管理跟踪的文件"
  1.4151 +
  1.4152 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4153 +#: ../en/ch04-concepts.xml:65
  1.4154 +msgid ""
  1.4155 +"Mercurial uses a structure called a <emphasis>manifest</emphasis> to collect "
  1.4156 +"together information about the files that it tracks.  Each entry in the "
  1.4157 +"manifest contains information about the files present in a single changeset.  "
  1.4158 +"An entry records which files are present in the changeset, the revision of "
  1.4159 +"each file, and a few other pieces of file metadata."
  1.4160 +msgstr ""
  1.4161 +
  1.4162 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4163 +#: ../en/ch04-concepts.xml:75
  1.4164 +msgid "Recording changeset information"
  1.4165 +msgstr "记录修改集信息"
  1.4166 +
  1.4167 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4168 +#: ../en/ch04-concepts.xml:77
  1.4169 +msgid ""
  1.4170 +"The <emphasis>changelog</emphasis> contains information about each "
  1.4171 +"changeset.  Each revision records who committed a change, the changeset "
  1.4172 +"comment, other pieces of changeset-related information, and the revision of "
  1.4173 +"the manifest to use."
  1.4174 +msgstr ""
  1.4175 +
  1.4176 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4177 +#: ../en/ch04-concepts.xml:85
  1.4178 +msgid "Relationships between revisions"
  1.4179 +msgstr "版本之间的关系"
  1.4180 +
  1.4181 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4182 +#: ../en/ch04-concepts.xml:87
  1.4183 +msgid ""
  1.4184 +"Within a changelog, a manifest, or a filelog, each revision stores a pointer "
  1.4185 +"to its immediate parent (or to its two parents, if it's a merge revision).  "
  1.4186 +"As I mentioned above, there are also relationships between revisions "
  1.4187 +"<emphasis>across</emphasis> these structures, and they are hierarchical in "
  1.4188 +"nature."
  1.4189 +msgstr ""
  1.4190 +
  1.4191 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4192 +#: ../en/ch04-concepts.xml:94
  1.4193 +msgid ""
  1.4194 +"For every changeset in a repository, there is exactly one revision stored in "
  1.4195 +"the changelog.  Each revision of the changelog contains a pointer to a single "
  1.4196 +"revision of the manifest.  A revision of the manifest stores a pointer to a "
  1.4197 +"single revision of each filelog tracked when that changeset was created.  "
  1.4198 +"These relationships are illustrated in figure <xref linkend=\"fig.concepts."
  1.4199 +"metadata\"/>."
  1.4200 +msgstr ""
  1.4201 +
  1.4202 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4203 +#: ../en/ch04-concepts.xml:103
  1.4204 +msgid "<imageobject><imagedata fileref=\"images/metadata.png\"/></imageobject>"
  1.4205 +msgstr ""
  1.4206 +
  1.4207 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4208 +#: ../en/ch04-concepts.xml:105
  1.4209 +msgid "Metadata relationships"
  1.4210 +msgstr ""
  1.4211 +
  1.4212 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4213 +#: ../en/ch04-concepts.xml:110
  1.4214 +msgid ""
  1.4215 +"As the illustration shows, there is <emphasis>not</emphasis> a <quote>one to "
  1.4216 +"one</quote> relationship between revisions in the changelog, manifest, or "
  1.4217 +"filelog. If the manifest hasn't changed between two changesets, the changelog "
  1.4218 +"entries for those changesets will point to the same revision of the "
  1.4219 +"manifest.  If a file that Mercurial tracks hasn't changed between two "
  1.4220 +"changesets, the entry for that file in the two revisions of the manifest will "
  1.4221 +"point to the same revision of its filelog."
  1.4222 +msgstr ""
  1.4223 +
  1.4224 +#. type: Content of: <book><chapter><sect1><title>
  1.4225 +#: ../en/ch04-concepts.xml:123
  1.4226 +msgid "Safe, efficient storage"
  1.4227 +msgstr "安全，高效的存储"
  1.4228 +
  1.4229 +#. type: Content of: <book><chapter><sect1><para>
  1.4230 +#: ../en/ch04-concepts.xml:125
  1.4231 +msgid ""
  1.4232 +"The underpinnings of changelogs, manifests, and filelogs are provided by a "
  1.4233 +"single structure called the <emphasis>revlog</emphasis>."
  1.4234 +msgstr ""
  1.4235 +
  1.4236 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4237 +#: ../en/ch04-concepts.xml:130
  1.4238 +msgid "Efficient storage"
  1.4239 +msgstr "高效存储"
  1.4240 +
  1.4241 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4242 +#: ../en/ch04-concepts.xml:132
  1.4243 +msgid ""
  1.4244 +"The revlog provides efficient storage of revisions using a <emphasis>delta</"
  1.4245 +"emphasis> mechanism.  Instead of storing a complete copy of a file for each "
  1.4246 +"revision, it stores the changes needed to transform an older revision into "
  1.4247 +"the new revision.  For many kinds of file data, these deltas are typically a "
  1.4248 +"fraction of a percent of the size of a full copy of a file."
  1.4249 +msgstr ""
  1.4250 +
  1.4251 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4252 +#: ../en/ch04-concepts.xml:140
  1.4253 +msgid ""
  1.4254 +"Some obsolete revision control systems can only work with deltas of text "
  1.4255 +"files.  They must either store binary files as complete snapshots or encoded "
  1.4256 +"into a text representation, both of which are wasteful approaches.  Mercurial "
  1.4257 +"can efficiently handle deltas of files with arbitrary binary contents; it "
  1.4258 +"doesn't need to treat text as special."
  1.4259 +msgstr ""
  1.4260 +
  1.4261 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4262 +#: ../en/ch04-concepts.xml:149
  1.4263 +msgid "Safe operation"
  1.4264 +msgstr "安全操作"
  1.4265 +
  1.4266 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4267 +#: ../en/ch04-concepts.xml:151
  1.4268 +msgid ""
  1.4269 +"Mercurial only ever <emphasis>appends</emphasis> data to the end of a revlog "
  1.4270 +"file. It never modifies a section of a file after it has written it.  This is "
  1.4271 +"both more robust and efficient than schemes that need to modify or rewrite "
  1.4272 +"data."
  1.4273 +msgstr ""
  1.4274 +
  1.4275 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4276 +#: ../en/ch04-concepts.xml:157
  1.4277 +msgid ""
  1.4278 +"In addition, Mercurial treats every write as part of a <emphasis>transaction</"
  1.4279 +"emphasis> that can span a number of files.  A transaction is "
  1.4280 +"<emphasis>atomic</emphasis>: either the entire transaction succeeds and its "
  1.4281 +"effects are all visible to readers in one go, or the whole thing is undone.  "
  1.4282 +"This guarantee of atomicity means that if you're running two copies of "
  1.4283 +"Mercurial, where one is reading data and one is writing it, the reader will "
  1.4284 +"never see a partially written result that might confuse it."
  1.4285 +msgstr ""
  1.4286 +
  1.4287 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4288 +#: ../en/ch04-concepts.xml:167
  1.4289 +msgid ""
  1.4290 +"The fact that Mercurial only appends to files makes it easier to provide this "
  1.4291 +"transactional guarantee.  The easier it is to do stuff like this, the more "
  1.4292 +"confident you should be that it's done correctly."
  1.4293 +msgstr ""
  1.4294 +
  1.4295 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4296 +#: ../en/ch04-concepts.xml:174
  1.4297 +msgid "Fast retrieval"
  1.4298 +msgstr "快速检索"
  1.4299 +
  1.4300 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4301 +#: ../en/ch04-concepts.xml:176
  1.4302 +msgid ""
  1.4303 +"Mercurial cleverly avoids a pitfall common to all earlier revision control "
  1.4304 +"systems: the problem of <emphasis>inefficient retrieval</emphasis>. Most "
  1.4305 +"revision control systems store the contents of a revision as an incremental "
  1.4306 +"series of modifications against a <quote>snapshot</quote>.  To reconstruct a "
  1.4307 +"specific revision, you must first read the snapshot, and then every one of "
  1.4308 +"the revisions between the snapshot and your target revision.  The more "
  1.4309 +"history that a file accumulates, the more revisions you must read, hence the "
  1.4310 +"longer it takes to reconstruct a particular revision."
  1.4311 +msgstr ""
  1.4312 +
  1.4313 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4314 +#: ../en/ch04-concepts.xml:188
  1.4315 +msgid "<imageobject><imagedata fileref=\"images/snapshot.png\"/></imageobject>"
  1.4316 +msgstr ""
  1.4317 +
  1.4318 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4319 +#: ../en/ch04-concepts.xml:190
  1.4320 +msgid "Snapshot of a revlog, with incremental deltas"
  1.4321 +msgstr ""
  1.4322 +
  1.4323 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4324 +#: ../en/ch04-concepts.xml:195
  1.4325 +msgid ""
  1.4326 +"The innovation that Mercurial applies to this problem is simple but "
  1.4327 +"effective.  Once the cumulative amount of delta information stored since the "
  1.4328 +"last snapshot exceeds a fixed threshold, it stores a new snapshot "
  1.4329 +"(compressed, of course), instead of another delta.  This makes it possible to "
  1.4330 +"reconstruct <emphasis>any</emphasis> revision of a file quickly.  This "
  1.4331 +"approach works so well that it has since been copied by several other "
  1.4332 +"revision control systems."
  1.4333 +msgstr ""
  1.4334 +
  1.4335 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4336 +#: ../en/ch04-concepts.xml:204
  1.4337 +msgid ""
  1.4338 +"Figure <xref linkend=\"fig.concepts.snapshot\"/> illustrates the idea.  In an "
  1.4339 +"entry in a revlog's index file, Mercurial stores the range of entries from "
  1.4340 +"the data file that it must read to reconstruct a particular revision."
  1.4341 +msgstr ""
  1.4342 +
  1.4343 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.4344 +#: ../en/ch04-concepts.xml:210
  1.4345 +msgid "Aside: the influence of video compression"
  1.4346 +msgstr ""
  1.4347 +
  1.4348 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.4349 +#: ../en/ch04-concepts.xml:212
  1.4350 +msgid ""
  1.4351 +"If you're familiar with video compression or have ever watched a TV feed "
  1.4352 +"through a digital cable or satellite service, you may know that most video "
  1.4353 +"compression schemes store each frame of video as a delta against its "
  1.4354 +"predecessor frame.  In addition, these schemes use <quote>lossy</quote> "
  1.4355 +"compression techniques to increase the compression ratio, so visual errors "
  1.4356 +"accumulate over the course of a number of inter-frame deltas."
  1.4357 +msgstr ""
  1.4358 +
  1.4359 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.4360 +#: ../en/ch04-concepts.xml:221
  1.4361 +msgid ""
  1.4362 +"Because it's possible for a video stream to <quote>drop out</quote> "
  1.4363 +"occasionally due to signal glitches, and to limit the accumulation of "
  1.4364 +"artefacts introduced by the lossy compression process, video encoders "
  1.4365 +"periodically insert a complete frame (called a <quote>key frame</quote>) into "
  1.4366 +"the video stream; the next delta is generated against that frame.  This means "
  1.4367 +"that if the video signal gets interrupted, it will resume once the next key "
  1.4368 +"frame is received.  Also, the accumulation of encoding errors restarts anew "
  1.4369 +"with each key frame."
  1.4370 +msgstr ""
  1.4371 +
  1.4372 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4373 +#: ../en/ch04-concepts.xml:235
  1.4374 +msgid "Identification and strong integrity"
  1.4375 +msgstr "鉴别和强完整性"
  1.4376 +
  1.4377 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4378 +#: ../en/ch04-concepts.xml:237
  1.4379 +msgid ""
  1.4380 +"Along with delta or snapshot information, a revlog entry contains a "
  1.4381 +"cryptographic hash of the data that it represents.  This makes it difficult "
  1.4382 +"to forge the contents of a revision, and easy to detect accidental corruption."
  1.4383 +msgstr ""
  1.4384 +
  1.4385 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4386 +#: ../en/ch04-concepts.xml:242
  1.4387 +msgid ""
  1.4388 +"Hashes provide more than a mere check against corruption; they are used as "
  1.4389 +"the identifiers for revisions.  The changeset identification hashes that you "
  1.4390 +"see as an end user are from revisions of the changelog.  Although filelogs "
  1.4391 +"and the manifest also use hashes, Mercurial only uses these behind the scenes."
  1.4392 +msgstr ""
  1.4393 +
  1.4394 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4395 +#: ../en/ch04-concepts.xml:249
  1.4396 +msgid ""
  1.4397 +"Mercurial verifies that hashes are correct when it retrieves file revisions "
  1.4398 +"and when it pulls changes from another repository.  If it encounters an "
  1.4399 +"integrity problem, it will complain and stop whatever it's doing."
  1.4400 +msgstr ""
  1.4401 +
  1.4402 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4403 +#: ../en/ch04-concepts.xml:254
  1.4404 +msgid ""
  1.4405 +"In addition to the effect it has on retrieval efficiency, Mercurial's use of "
  1.4406 +"periodic snapshots makes it more robust against partial data corruption.  If "
  1.4407 +"a revlog becomes partly corrupted due to a hardware error or system bug, it's "
  1.4408 +"often possible to reconstruct some or most revisions from the uncorrupted "
  1.4409 +"sections of the revlog, both before and after the corrupted section.  This "
  1.4410 +"would not be possible with a delta-only storage model."
  1.4411 +msgstr ""
  1.4412 +
  1.4413 +#. type: Content of: <book><chapter><sect1><title>
  1.4414 +#: ../en/ch04-concepts.xml:266
  1.4415 +msgid "Revision history, branching, and merging"
  1.4416 +msgstr "修订历史，分支与合并"
  1.4417 +
  1.4418 +#. type: Content of: <book><chapter><sect1><para>
  1.4419 +#: ../en/ch04-concepts.xml:268
  1.4420 +msgid ""
  1.4421 +"Every entry in a Mercurial revlog knows the identity of its immediate "
  1.4422 +"ancestor revision, usually referred to as its <emphasis>parent</emphasis>.  "
  1.4423 +"In fact, a revision contains room for not one parent, but two.  Mercurial "
  1.4424 +"uses a special hash, called the <quote>null ID</quote>, to represent the idea "
  1.4425 +"<quote>there is no parent here</quote>.  This hash is simply a string of "
  1.4426 +"zeroes."
  1.4427 +msgstr ""
  1.4428 +
  1.4429 +#. type: Content of: <book><chapter><sect1><para>
  1.4430 +#: ../en/ch04-concepts.xml:276
  1.4431 +msgid ""
  1.4432 +"In figure <xref linkend=\"fig.concepts.revlog\"/>, you can see an example of "
  1.4433 +"the conceptual structure of a revlog.  Filelogs, manifests, and changelogs "
  1.4434 +"all have this same structure; they differ only in the kind of data stored in "
  1.4435 +"each delta or snapshot."
  1.4436 +msgstr ""
  1.4437 +
  1.4438 +#. type: Content of: <book><chapter><sect1><para>
  1.4439 +#: ../en/ch04-concepts.xml:282
  1.4440 +msgid ""
  1.4441 +"The first revision in a revlog (at the bottom of the image)  has the null ID "
  1.4442 +"in both of its parent slots.  For a <quote>normal</quote> revision, its first "
  1.4443 +"parent slot contains the ID of its parent revision, and its second contains "
  1.4444 +"the null ID, indicating that the revision has only one real parent.  Any two "
  1.4445 +"revisions that have the same parent ID are branches.  A revision that "
  1.4446 +"represents a merge between branches has two normal revision IDs in its parent "
  1.4447 +"slots."
  1.4448 +msgstr ""
  1.4449 +
  1.4450 +#. type: Content of: <book><chapter><sect1><informalfigure><mediaobject>
  1.4451 +#: ../en/ch04-concepts.xml:292
  1.4452 +msgid "<imageobject><imagedata fileref=\"images/revlog.png\"/></imageobject>"
  1.4453 +msgstr ""
  1.4454 +
  1.4455 +#. type: Content of: <book><chapter><sect1><title>
  1.4456 +#: ../en/ch04-concepts.xml:299
  1.4457 +msgid "The working directory"
  1.4458 +msgstr "工作目录"
  1.4459 +
  1.4460 +#. type: Content of: <book><chapter><sect1><para>
  1.4461 +#: ../en/ch04-concepts.xml:301
  1.4462 +msgid ""
  1.4463 +"In the working directory, Mercurial stores a snapshot of the files from the "
  1.4464 +"repository as of a particular changeset."
  1.4465 +msgstr ""
  1.4466 +
  1.4467 +#. type: Content of: <book><chapter><sect1><para>
  1.4468 +#: ../en/ch04-concepts.xml:304
  1.4469 +msgid ""
  1.4470 +"The working directory <quote>knows</quote> which changeset it contains.  When "
  1.4471 +"you update the working directory to contain a particular changeset, Mercurial "
  1.4472 +"looks up the appropriate revision of the manifest to find out which files it "
  1.4473 +"was tracking at the time that changeset was committed, and which revision of "
  1.4474 +"each file was then current.  It then recreates a copy of each of those files, "
  1.4475 +"with the same contents it had when the changeset was committed."
  1.4476 +msgstr ""
  1.4477 +
  1.4478 +#. type: Content of: <book><chapter><sect1><para>
  1.4479 +#: ../en/ch04-concepts.xml:313
  1.4480 +msgid ""
  1.4481 +"The <emphasis>dirstate</emphasis> contains Mercurial's knowledge of the "
  1.4482 +"working directory.  This details which changeset the working directory is "
  1.4483 +"updated to, and all of the files that Mercurial is tracking in the working "
  1.4484 +"directory."
  1.4485 +msgstr ""
  1.4486 +
  1.4487 +#. type: Content of: <book><chapter><sect1><para>
  1.4488 +#: ../en/ch04-concepts.xml:319
  1.4489 +msgid ""
  1.4490 +"Just as a revision of a revlog has room for two parents, so that it can "
  1.4491 +"represent either a normal revision (with one parent)  or a merge of two "
  1.4492 +"earlier revisions, the dirstate has slots for two parents.  When you use the "
  1.4493 +"<command role=\"hg-cmd\">hg update</command> command, the changeset that you "
  1.4494 +"update to is stored in the <quote>first parent</quote> slot, and the null ID "
  1.4495 +"in the second. When you <command role=\"hg-cmd\">hg merge</command> with "
  1.4496 +"another changeset, the first parent remains unchanged, and the second parent "
  1.4497 +"is filled in with the changeset you're merging with.  The <command role=\"hg-"
  1.4498 +"cmd\">hg parents</command> command tells you what the parents of the dirstate "
  1.4499 +"are."
  1.4500 +msgstr ""
  1.4501 +
  1.4502 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4503 +#: ../en/ch04-concepts.xml:333
  1.4504 +msgid "What happens when you commit"
  1.4505 +msgstr "当你提交时发生的事情"
  1.4506 +
  1.4507 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4508 +#: ../en/ch04-concepts.xml:335
  1.4509 +msgid ""
  1.4510 +"The dirstate stores parent information for more than just book-keeping "
  1.4511 +"purposes.  Mercurial uses the parents of the dirstate as <emphasis>the "
  1.4512 +"parents of a new changeset</emphasis> when you perform a commit."
  1.4513 +msgstr ""
  1.4514 +
  1.4515 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4516 +#: ../en/ch04-concepts.xml:341
  1.4517 +msgid "<imageobject><imagedata fileref=\"images/wdir.png\"/></imageobject>"
  1.4518 +msgstr ""
  1.4519 +
  1.4520 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4521 +#: ../en/ch04-concepts.xml:343
  1.4522 +msgid "The working directory can have two parents"
  1.4523 +msgstr ""
  1.4524 +
  1.4525 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4526 +#: ../en/ch04-concepts.xml:348
  1.4527 +msgid ""
  1.4528 +"Figure <xref linkend=\"fig.concepts.wdir\"/> shows the normal state of the "
  1.4529 +"working directory, where it has a single changeset as parent.  That changeset "
  1.4530 +"is the <emphasis>tip</emphasis>, the newest changeset in the repository that "
  1.4531 +"has no children."
  1.4532 +msgstr ""
  1.4533 +
  1.4534 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4535 +#: ../en/ch04-concepts.xml:355
  1.4536 +msgid ""
  1.4537 +"<imageobject><imagedata fileref=\"images/wdir-after-commit.png\"/></"
  1.4538 +"imageobject>"
  1.4539 +msgstr ""
  1.4540 +
  1.4541 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4542 +#: ../en/ch04-concepts.xml:357
  1.4543 +msgid "The working directory gains new parents after a commit"
  1.4544 +msgstr ""
  1.4545 +
  1.4546 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4547 +#: ../en/ch04-concepts.xml:362
  1.4548 +msgid ""
  1.4549 +"It's useful to think of the working directory as <quote>the changeset I'm "
  1.4550 +"about to commit</quote>.  Any files that you tell Mercurial that you've "
  1.4551 +"added, removed, renamed, or copied will be reflected in that changeset, as "
  1.4552 +"will modifications to any files that Mercurial is already tracking; the new "
  1.4553 +"changeset will have the parents of the working directory as its parents."
  1.4554 +msgstr ""
  1.4555 +
  1.4556 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4557 +#: ../en/ch04-concepts.xml:370
  1.4558 +msgid ""
  1.4559 +"After a commit, Mercurial will update the parents of the working directory, "
  1.4560 +"so that the first parent is the ID of the new changeset, and the second is "
  1.4561 +"the null ID.  This is shown in figure <xref linkend=\"fig.concepts.wdir-after-"
  1.4562 +"commit\"/>.  Mercurial doesn't touch any of the files in the working "
  1.4563 +"directory when you commit; it just modifies the dirstate to note its new "
  1.4564 +"parents."
  1.4565 +msgstr ""
  1.4566 +
  1.4567 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4568 +#: ../en/ch04-concepts.xml:381
  1.4569 +msgid "Creating a new head"
  1.4570 +msgstr "创建新顶点"
  1.4571 +
  1.4572 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4573 +#: ../en/ch04-concepts.xml:383
  1.4574 +msgid ""
  1.4575 +"It's perfectly normal to update the working directory to a changeset other "
  1.4576 +"than the current tip.  For example, you might want to know what your project "
  1.4577 +"looked like last Tuesday, or you could be looking through changesets to see "
  1.4578 +"which one introduced a bug.  In cases like this, the natural thing to do is "
  1.4579 +"update the working directory to the changeset you're interested in, and then "
  1.4580 +"examine the files in the working directory directly to see their contents as "
  1.4581 +"they were when you committed that changeset.  The effect of this is shown in "
  1.4582 +"figure <xref linkend=\"fig.concepts.wdir-pre-branch\"/>."
  1.4583 +msgstr ""
  1.4584 +
  1.4585 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4586 +#: ../en/ch04-concepts.xml:395
  1.4587 +msgid ""
  1.4588 +"<imageobject><imagedata fileref=\"images/wdir-pre-branch.png\"/></imageobject>"
  1.4589 +msgstr ""
  1.4590 +
  1.4591 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4592 +#: ../en/ch04-concepts.xml:397
  1.4593 +msgid "The working directory, updated to an older changeset"
  1.4594 +msgstr ""
  1.4595 +
  1.4596 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4597 +#: ../en/ch04-concepts.xml:402
  1.4598 +msgid ""
  1.4599 +"Having updated the working directory to an older changeset, what happens if "
  1.4600 +"you make some changes, and then commit? Mercurial behaves in the same way as "
  1.4601 +"I outlined above.  The parents of the working directory become the parents of "
  1.4602 +"the new changeset.  This new changeset has no children, so it becomes the new "
  1.4603 +"tip.  And the repository now contains two changesets that have no children; "
  1.4604 +"we call these <emphasis>heads</emphasis>.  You can see the structure that "
  1.4605 +"this creates in figure <xref linkend=\"fig.concepts.wdir-branch\"/>."
  1.4606 +msgstr ""
  1.4607 +
  1.4608 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4609 +#: ../en/ch04-concepts.xml:414
  1.4610 +msgid ""
  1.4611 +"<imageobject><imagedata fileref=\"images/wdir-branch.png\"/></imageobject>"
  1.4612 +msgstr ""
  1.4613 +
  1.4614 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4615 +#: ../en/ch04-concepts.xml:416
  1.4616 +msgid "After a commit made while synced to an older changeset"
  1.4617 +msgstr ""
  1.4618 +
  1.4619 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
  1.4620 +#: ../en/ch04-concepts.xml:422
  1.4621 +msgid ""
  1.4622 +"If you're new to Mercurial, you should keep in mind a common <quote>error</"
  1.4623 +"quote>, which is to use the <command role=\"hg-cmd\">hg pull</command> "
  1.4624 +"command without any options.  By default, the <command role=\"hg-cmd\">hg "
  1.4625 +"pull</command> command <emphasis>does not</emphasis> update the working "
  1.4626 +"directory, so you'll bring new changesets into your repository, but the "
  1.4627 +"working directory will stay synced at the same changeset as before the pull.  "
  1.4628 +"If you make some changes and commit afterwards, you'll thus create a new "
  1.4629 +"head, because your working directory isn't synced to whatever the current tip "
  1.4630 +"is."
  1.4631 +msgstr ""
  1.4632 +
  1.4633 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
  1.4634 +#: ../en/ch04-concepts.xml:434
  1.4635 +msgid ""
  1.4636 +"I put the word <quote>error</quote> in quotes because all that you need to do "
  1.4637 +"to rectify this situation is <command role=\"hg-cmd\">hg merge</command>, "
  1.4638 +"then <command role=\"hg-cmd\">hg commit</command>.  In other words, this "
  1.4639 +"almost never has negative consequences; it just surprises people.  I'll "
  1.4640 +"discuss other ways to avoid this behaviour, and why Mercurial behaves in this "
  1.4641 +"initially surprising way, later on."
  1.4642 +msgstr ""
  1.4643 +
  1.4644 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4645 +#: ../en/ch04-concepts.xml:446
  1.4646 +msgid "Merging heads"
  1.4647 +msgstr "合并顶点"
  1.4648 +
  1.4649 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4650 +#: ../en/ch04-concepts.xml:448
  1.4651 +msgid ""
  1.4652 +"When you run the <command role=\"hg-cmd\">hg merge</command> command, "
  1.4653 +"Mercurial leaves the first parent of the working directory unchanged, and "
  1.4654 +"sets the second parent to the changeset you're merging with, as shown in "
  1.4655 +"figure <xref linkend=\"fig.concepts.wdir-merge\"/>."
  1.4656 +msgstr ""
  1.4657 +
  1.4658 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.4659 +#: ../en/ch04-concepts.xml:455
  1.4660 +msgid ""
  1.4661 +"<imageobject><imagedata fileref=\"images/wdir-merge.png\"/></imageobject>"
  1.4662 +msgstr ""
  1.4663 +
  1.4664 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.4665 +#: ../en/ch04-concepts.xml:457
  1.4666 +msgid "Merging two heads"
  1.4667 +msgstr ""
  1.4668 +
  1.4669 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4670 +#: ../en/ch04-concepts.xml:461
  1.4671 +msgid ""
  1.4672 +"Mercurial also has to modify the working directory, to merge the files "
  1.4673 +"managed in the two changesets.  Simplified a little, the merging process goes "
  1.4674 +"like this, for every file in the manifests of both changesets."
  1.4675 +msgstr ""
  1.4676 +
  1.4677 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.4678 +#: ../en/ch04-concepts.xml:466
  1.4679 +msgid "If neither changeset has modified a file, do nothing with that file."
  1.4680 +msgstr ""
  1.4681 +
  1.4682 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.4683 +#: ../en/ch04-concepts.xml:469
  1.4684 +msgid ""
  1.4685 +"If one changeset has modified a file, and the other hasn't, create the "
  1.4686 +"modified copy of the file in the working directory."
  1.4687 +msgstr ""
  1.4688 +
  1.4689 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.4690 +#: ../en/ch04-concepts.xml:473
  1.4691 +msgid ""
  1.4692 +"If one changeset has removed a file, and the other hasn't (or has also "
  1.4693 +"deleted it), delete the file from the working directory."
  1.4694 +msgstr ""
  1.4695 +
  1.4696 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.4697 +#: ../en/ch04-concepts.xml:477
  1.4698 +msgid ""
  1.4699 +"If one changeset has removed a file, but the other has modified the file, ask "
  1.4700 +"the user what to do: keep the modified file, or remove it?"
  1.4701 +msgstr ""
  1.4702 +
  1.4703 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.4704 +#: ../en/ch04-concepts.xml:481
  1.4705 +msgid ""
  1.4706 +"If both changesets have modified a file, invoke an external merge program to "
  1.4707 +"choose the new contents for the merged file.  This may require input from the "
  1.4708 +"user."
  1.4709 +msgstr ""
  1.4710 +
  1.4711 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.4712 +#: ../en/ch04-concepts.xml:486
  1.4713 +msgid ""
  1.4714 +"If one changeset has modified a file, and the other has renamed or copied the "
  1.4715 +"file, make sure that the changes follow the new name of the file."
  1.4716 +msgstr ""
  1.4717 +
  1.4718 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4719 +#: ../en/ch04-concepts.xml:490
  1.4720 +msgid ""
  1.4721 +"There are more details&emdash;merging has plenty of corner cases&emdash;but "
  1.4722 +"these are the most common choices that are involved in a merge.  As you can "
  1.4723 +"see, most cases are completely automatic, and indeed most merges finish "
  1.4724 +"automatically, without requiring your input to resolve any conflicts."
  1.4725 +msgstr ""
  1.4726 +
  1.4727 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4728 +#: ../en/ch04-concepts.xml:497
  1.4729 +msgid ""
  1.4730 +"When you're thinking about what happens when you commit after a merge, once "
  1.4731 +"again the working directory is <quote>the changeset I'm about to commit</"
  1.4732 +"quote>.  After the <command role=\"hg-cmd\">hg merge</command> command "
  1.4733 +"completes, the working directory has two parents; these will become the "
  1.4734 +"parents of the new changeset."
  1.4735 +msgstr ""
  1.4736 +
  1.4737 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4738 +#: ../en/ch04-concepts.xml:504
  1.4739 +msgid ""
  1.4740 +"Mercurial lets you perform multiple merges, but you must commit the results "
  1.4741 +"of each individual merge as you go.  This is necessary because Mercurial only "
  1.4742 +"tracks two parents for both revisions and the working directory.  While it "
  1.4743 +"would be technically possible to merge multiple changesets at once, the "
  1.4744 +"prospect of user confusion and making a terrible mess of a merge immediately "
  1.4745 +"becomes overwhelming."
  1.4746 +msgstr ""
  1.4747 +
  1.4748 +#. type: Content of: <book><chapter><sect1><title>
  1.4749 +#: ../en/ch04-concepts.xml:515
  1.4750 +msgid "Other interesting design features"
  1.4751 +msgstr "其它有趣的设计特性"
  1.4752 +
  1.4753 +#. type: Content of: <book><chapter><sect1><para>
  1.4754 +#: ../en/ch04-concepts.xml:517
  1.4755 +msgid ""
  1.4756 +"In the sections above, I've tried to highlight some of the most important "
  1.4757 +"aspects of Mercurial's design, to illustrate that it pays careful attention "
  1.4758 +"to reliability and performance.  However, the attention to detail doesn't "
  1.4759 +"stop there.  There are a number of other aspects of Mercurial's construction "
  1.4760 +"that I personally find interesting.  I'll detail a few of them here, separate "
  1.4761 +"from the <quote>big ticket</quote> items above, so that if you're interested, "
  1.4762 +"you can gain a better idea of the amount of thinking that goes into a well-"
  1.4763 +"designed system."
  1.4764 +msgstr ""
  1.4765 +
  1.4766 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4767 +#: ../en/ch04-concepts.xml:528
  1.4768 +msgid "Clever compression"
  1.4769 +msgstr "智能压缩"
  1.4770 +
  1.4771 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4772 +#: ../en/ch04-concepts.xml:530
  1.4773 +msgid ""
  1.4774 +"When appropriate, Mercurial will store both snapshots and deltas in "
  1.4775 +"compressed form.  It does this by always <emphasis>trying to</emphasis> "
  1.4776 +"compress a snapshot or delta, but only storing the compressed version if it's "
  1.4777 +"smaller than the uncompressed version."
  1.4778 +msgstr ""
  1.4779 +
  1.4780 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4781 +#: ../en/ch04-concepts.xml:536
  1.4782 +msgid ""
  1.4783 +"This means that Mercurial does <quote>the right thing</quote> when storing a "
  1.4784 +"file whose native form is compressed, such as a <literal>zip</literal> "
  1.4785 +"archive or a JPEG image.  When these types of files are compressed a second "
  1.4786 +"time, the resulting file is usually bigger than the once-compressed form, and "
  1.4787 +"so Mercurial will store the plain <literal>zip</literal> or JPEG."
  1.4788 +msgstr ""
  1.4789 +
  1.4790 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4791 +#: ../en/ch04-concepts.xml:544
  1.4792 +msgid ""
  1.4793 +"Deltas between revisions of a compressed file are usually larger than "
  1.4794 +"snapshots of the file, and Mercurial again does <quote>the right thing</"
  1.4795 +"quote> in these cases.  It finds that such a delta exceeds the threshold at "
  1.4796 +"which it should store a complete snapshot of the file, so it stores the "
  1.4797 +"snapshot, again saving space compared to a naive delta-only approach."
  1.4798 +msgstr ""
  1.4799 +
  1.4800 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.4801 +#: ../en/ch04-concepts.xml:553
  1.4802 +msgid "Network recompression"
  1.4803 +msgstr "网络重新压缩"
  1.4804 +
  1.4805 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.4806 +#: ../en/ch04-concepts.xml:555
  1.4807 +msgid ""
  1.4808 +"When storing revisions on disk, Mercurial uses the <quote>deflate</quote> "
  1.4809 +"compression algorithm (the same one used by the popular <literal>zip</"
  1.4810 +"literal> archive format), which balances good speed with a respectable "
  1.4811 +"compression ratio.  However, when transmitting revision data over a network "
  1.4812 +"connection, Mercurial uncompresses the compressed revision data."
  1.4813 +msgstr ""
  1.4814 +
  1.4815 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.4816 +#: ../en/ch04-concepts.xml:563
  1.4817 +msgid ""
  1.4818 +"If the connection is over HTTP, Mercurial recompresses the entire stream of "
  1.4819 +"data using a compression algorithm that gives a better compression ratio (the "
  1.4820 +"Burrows-Wheeler algorithm from the widely used <literal>bzip2</literal> "
  1.4821 +"compression package).  This combination of algorithm and compression of the "
  1.4822 +"entire stream (instead of a revision at a time) substantially reduces the "
  1.4823 +"number of bytes to be transferred, yielding better network performance over "
  1.4824 +"almost all kinds of network."
  1.4825 +msgstr ""
  1.4826 +
  1.4827 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.4828 +#: ../en/ch04-concepts.xml:573
  1.4829 +msgid ""
  1.4830 +"(If the connection is over <command>ssh</command>, Mercurial "
  1.4831 +"<emphasis>doesn't</emphasis> recompress the stream, because <command>ssh</"
  1.4832 +"command> can already do this itself.)"
  1.4833 +msgstr ""
  1.4834 +
  1.4835 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4836 +#: ../en/ch04-concepts.xml:581
  1.4837 +msgid "Read/write ordering and atomicity"
  1.4838 +msgstr "读写顺序与原子性"
  1.4839 +
  1.4840 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4841 +#: ../en/ch04-concepts.xml:583
  1.4842 +msgid ""
  1.4843 +"Appending to files isn't the whole story when it comes to guaranteeing that a "
  1.4844 +"reader won't see a partial write.  If you recall figure <xref linkend=\"fig."
  1.4845 +"concepts.metadata\"/>, revisions in the changelog point to revisions in the "
  1.4846 +"manifest, and revisions in the manifest point to revisions in filelogs.  This "
  1.4847 +"hierarchy is deliberate."
  1.4848 +msgstr ""
  1.4849 +
  1.4850 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4851 +#: ../en/ch04-concepts.xml:591
  1.4852 +msgid ""
  1.4853 +"A writer starts a transaction by writing filelog and manifest data, and "
  1.4854 +"doesn't write any changelog data until those are finished.  A reader starts "
  1.4855 +"by reading changelog data, then manifest data, followed by filelog data."
  1.4856 +msgstr ""
  1.4857 +
  1.4858 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4859 +#: ../en/ch04-concepts.xml:596
  1.4860 +msgid ""
  1.4861 +"Since the writer has always finished writing filelog and manifest data before "
  1.4862 +"it writes to the changelog, a reader will never read a pointer to a partially "
  1.4863 +"written manifest revision from the changelog, and it will never read a "
  1.4864 +"pointer to a partially written filelog revision from the manifest."
  1.4865 +msgstr ""
  1.4866 +
  1.4867 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4868 +#: ../en/ch04-concepts.xml:604
  1.4869 +msgid "Concurrent access"
  1.4870 +msgstr "并发访问"
  1.4871 +
  1.4872 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4873 +#: ../en/ch04-concepts.xml:606
  1.4874 +msgid ""
  1.4875 +"The read/write ordering and atomicity guarantees mean that Mercurial never "
  1.4876 +"needs to <emphasis>lock</emphasis> a repository when it's reading data, even "
  1.4877 +"if the repository is being written to while the read is occurring. This has a "
  1.4878 +"big effect on scalability; you can have an arbitrary number of Mercurial "
  1.4879 +"processes safely reading data from a repository safely all at once, no matter "
  1.4880 +"whether it's being written to or not."
  1.4881 +msgstr ""
  1.4882 +
  1.4883 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4884 +#: ../en/ch04-concepts.xml:615
  1.4885 +msgid ""
  1.4886 +"The lockless nature of reading means that if you're sharing a repository on a "
  1.4887 +"multi-user system, you don't need to grant other local users permission to "
  1.4888 +"<emphasis>write</emphasis> to your repository in order for them to be able to "
  1.4889 +"clone it or pull changes from it; they only need <emphasis>read</emphasis> "
  1.4890 +"permission.  (This is <emphasis>not</emphasis> a common feature among "
  1.4891 +"revision control systems, so don't take it for granted! Most require readers "
  1.4892 +"to be able to lock a repository to access it safely, and this requires write "
  1.4893 +"permission on at least one directory, which of course makes for all kinds of "
  1.4894 +"nasty and annoying security and administrative problems.)"
  1.4895 +msgstr ""
  1.4896 +
  1.4897 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4898 +#: ../en/ch04-concepts.xml:628
  1.4899 +msgid ""
  1.4900 +"Mercurial uses locks to ensure that only one process can write to a "
  1.4901 +"repository at a time (the locking mechanism is safe even over filesystems "
  1.4902 +"that are notoriously hostile to locking, such as NFS).  If a repository is "
  1.4903 +"locked, a writer will wait for a while to retry if the repository becomes "
  1.4904 +"unlocked, but if the repository remains locked for too long, the process "
  1.4905 +"attempting to write will time out after a while. This means that your daily "
  1.4906 +"automated scripts won't get stuck forever and pile up if a system crashes "
  1.4907 +"unnoticed, for example.  (Yes, the timeout is configurable, from zero to "
  1.4908 +"infinity.)"
  1.4909 +msgstr ""
  1.4910 +
  1.4911 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.4912 +#: ../en/ch04-concepts.xml:640
  1.4913 +msgid "Safe dirstate access"
  1.4914 +msgstr "安全的目录状态访问"
  1.4915 +
  1.4916 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.4917 +#: ../en/ch04-concepts.xml:642
  1.4918 +msgid ""
  1.4919 +"As with revision data, Mercurial doesn't take a lock to read the dirstate "
  1.4920 +"file; it does acquire a lock to write it.  To avoid the possibility of "
  1.4921 +"reading a partially written copy of the dirstate file, Mercurial writes to a "
  1.4922 +"file with a unique name in the same directory as the dirstate file, then "
  1.4923 +"renames the temporary file atomically to <filename>dirstate</filename>.  The "
  1.4924 +"file named <filename>dirstate</filename> is thus guaranteed to be complete, "
  1.4925 +"not partially written."
  1.4926 +msgstr ""
  1.4927 +
  1.4928 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4929 +#: ../en/ch04-concepts.xml:655
  1.4930 +msgid "Avoiding seeks"
  1.4931 +msgstr "避免查找"
  1.4932 +
  1.4933 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4934 +#: ../en/ch04-concepts.xml:657
  1.4935 +msgid ""
  1.4936 +"Critical to Mercurial's performance is the avoidance of seeks of the disk "
  1.4937 +"head, since any seek is far more expensive than even a comparatively large "
  1.4938 +"read operation."
  1.4939 +msgstr ""
  1.4940 +
  1.4941 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4942 +#: ../en/ch04-concepts.xml:661
  1.4943 +msgid ""
  1.4944 +"This is why, for example, the dirstate is stored in a single file.  If there "
  1.4945 +"were a dirstate file per directory that Mercurial tracked, the disk would "
  1.4946 +"seek once per directory.  Instead, Mercurial reads the entire single dirstate "
  1.4947 +"file in one step."
  1.4948 +msgstr ""
  1.4949 +
  1.4950 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4951 +#: ../en/ch04-concepts.xml:667
  1.4952 +msgid ""
  1.4953 +"Mercurial also uses a <quote>copy on write</quote> scheme when cloning a "
  1.4954 +"repository on local storage.  Instead of copying every revlog file from the "
  1.4955 +"old repository into the new repository, it makes a <quote>hard link</quote>, "
  1.4956 +"which is a shorthand way to say <quote>these two names point to the same "
  1.4957 +"file</quote>.  When Mercurial is about to write to one of a revlog's files, "
  1.4958 +"it checks to see if the number of names pointing at the file is greater than "
  1.4959 +"one.  If it is, more than one repository is using the file, so Mercurial "
  1.4960 +"makes a new copy of the file that is private to this repository."
  1.4961 +msgstr ""
  1.4962 +
  1.4963 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4964 +#: ../en/ch04-concepts.xml:678
  1.4965 +msgid ""
  1.4966 +"A few revision control developers have pointed out that this idea of making a "
  1.4967 +"complete private copy of a file is not very efficient in its use of storage.  "
  1.4968 +"While this is true, storage is cheap, and this method gives the highest "
  1.4969 +"performance while deferring most book-keeping to the operating system.  An "
  1.4970 +"alternative scheme would most likely reduce performance and increase the "
  1.4971 +"complexity of the software, each of which is much more important to the "
  1.4972 +"<quote>feel</quote> of day-to-day use."
  1.4973 +msgstr ""
  1.4974 +
  1.4975 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.4976 +#: ../en/ch04-concepts.xml:690
  1.4977 +msgid "Other contents of the dirstate"
  1.4978 +msgstr "目录状态的其它内容"
  1.4979 +
  1.4980 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4981 +#: ../en/ch04-concepts.xml:692
  1.4982 +msgid ""
  1.4983 +"Because Mercurial doesn't force you to tell it when you're modifying a file, "
  1.4984 +"it uses the dirstate to store some extra information so it can determine "
  1.4985 +"efficiently whether you have modified a file.  For each file in the working "
  1.4986 +"directory, it stores the time that it last modified the file itself, and the "
  1.4987 +"size of the file at that time."
  1.4988 +msgstr ""
  1.4989 +
  1.4990 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.4991 +#: ../en/ch04-concepts.xml:699
  1.4992 +msgid ""
  1.4993 +"When you explicitly <command role=\"hg-cmd\">hg add</command>, <command role="
  1.4994 +"\"hg-cmd\">hg remove</command>, <command role=\"hg-cmd\">hg rename</command> "
  1.4995 +"or <command role=\"hg-cmd\">hg copy</command> files, Mercurial updates the "
  1.4996 +"dirstate so that it knows what to do with those files when you commit."
  1.4997 +msgstr ""
  1.4998 +
  1.4999 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5000 +#: ../en/ch04-concepts.xml:706
  1.5001 +msgid ""
  1.5002 +"When Mercurial is checking the states of files in the working directory, it "
  1.5003 +"first checks a file's modification time.  If that has not changed, the file "
  1.5004 +"must not have been modified.  If the file's size has changed, the file must "
  1.5005 +"have been modified.  If the modification time has changed, but the size has "
  1.5006 +"not, only then does Mercurial need to read the actual contents of the file to "
  1.5007 +"see if they've changed. Storing these few extra pieces of information "
  1.5008 +"dramatically reduces the amount of data that Mercurial needs to read, which "
  1.5009 +"yields large performance improvements compared to other revision control "
  1.5010 +"systems."
  1.5011 +msgstr ""
  1.5012 +
  1.5013 +#. type: Content of: <book><chapter><title>
  1.5014 +#: ../en/ch05-daily.xml:5
  1.5015 +msgid "Mercurial in daily use"
  1.5016 +msgstr "Mercurial 的日常使用"
  1.5017 +
  1.5018 +#. type: Content of: <book><chapter><sect1><title>
  1.5019 +#: ../en/ch05-daily.xml:8
  1.5020 +msgid "Telling Mercurial which files to track"
  1.5021 +msgstr "告诉 Mercurial 要跟踪哪些文件"
  1.5022 +
  1.5023 +#. type: Content of: <book><chapter><sect1><para>
  1.5024 +#: ../en/ch05-daily.xml:10
  1.5025 +msgid ""
  1.5026 +"Mercurial does not work with files in your repository unless you tell it to "
  1.5027 +"manage them.  The <command role=\"hg-cmd\">hg status</command> command will "
  1.5028 +"tell you which files Mercurial doesn't know about; it uses a <quote><literal>?"
  1.5029 +"</literal></quote> to display such files."
  1.5030 +msgstr ""
  1.5031 +
  1.5032 +#
  1.5033 +#. type: Content of: <book><chapter><sect1><para>
  1.5034 +#: ../en/ch05-daily.xml:17
  1.5035 +msgid ""
  1.5036 +"To tell Mercurial to track a file, use the <command role=\"hg-cmd\">hg add</"
  1.5037 +"command> command.  Once you have added a file, the entry in the output of "
  1.5038 +"<command role=\"hg-cmd\">hg status</command> for that file changes from "
  1.5039 +"<quote><literal>?</literal></quote> to <quote><literal>A</literal></quote>."
  1.5040 +msgstr ""
  1.5041 +
  1.5042 +#. type: Content of: <book><chapter><sect1><para>
  1.5043 +#: ../en/ch05-daily.xml:26
  1.5044 +msgid ""
  1.5045 +"After you run a <command role=\"hg-cmd\">hg commit</command>, the files that "
  1.5046 +"you added before the commit will no longer be listed in the output of "
  1.5047 +"<command role=\"hg-cmd\">hg status</command>.  The reason for this is that "
  1.5048 +"<command role=\"hg-cmd\">hg status</command> only tells you about "
  1.5049 +"<quote>interesting</quote> files&emdash;those that you have modified or told "
  1.5050 +"Mercurial to do something with&emdash;by default.  If you have a repository "
  1.5051 +"that contains thousands of files, you will rarely want to know about files "
  1.5052 +"that Mercurial is tracking, but that have not changed.  (You can still get "
  1.5053 +"this information; we'll return to this later.)"
  1.5054 +msgstr ""
  1.5055 +
  1.5056 +#. type: Content of: <book><chapter><sect1><para>
  1.5057 +#: ../en/ch05-daily.xml:38
  1.5058 +msgid ""
  1.5059 +"Once you add a file, Mercurial doesn't do anything with it immediately.  "
  1.5060 +"Instead, it will take a snapshot of the file's state the next time you "
  1.5061 +"perform a commit.  It will then continue to track the changes you make to the "
  1.5062 +"file every time you commit, until you remove the file."
  1.5063 +msgstr ""
  1.5064 +
  1.5065 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5066 +#: ../en/ch05-daily.xml:45
  1.5067 +msgid "Explicit versus implicit file naming"
  1.5068 +msgstr "明确与隐含文件命名"
  1.5069 +
  1.5070 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5071 +#: ../en/ch05-daily.xml:47
  1.5072 +msgid ""
  1.5073 +"A useful behaviour that Mercurial has is that if you pass the name of a "
  1.5074 +"directory to a command, every Mercurial command will treat this as <quote>I "
  1.5075 +"want to operate on every file in this directory and its subdirectories</"
  1.5076 +"quote>."
  1.5077 +msgstr ""
  1.5078 +
  1.5079 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5080 +#: ../en/ch05-daily.xml:54
  1.5081 +msgid ""
  1.5082 +"Notice in this example that Mercurial printed the names of the files it "
  1.5083 +"added, whereas it didn't do so when we added the file named <filename>a</"
  1.5084 +"filename> in the earlier example."
  1.5085 +msgstr ""
  1.5086 +
  1.5087 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5088 +#: ../en/ch05-daily.xml:59
  1.5089 +msgid ""
  1.5090 +"What's going on is that in the former case, we explicitly named the file to "
  1.5091 +"add on the command line, so the assumption that Mercurial makes in such cases "
  1.5092 +"is that you know what you were doing, and it doesn't print any output."
  1.5093 +msgstr ""
  1.5094 +
  1.5095 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5096 +#: ../en/ch05-daily.xml:64
  1.5097 +msgid ""
  1.5098 +"However, when we <emphasis>imply</emphasis> the names of files by giving the "
  1.5099 +"name of a directory, Mercurial takes the extra step of printing the name of "
  1.5100 +"each file that it does something with.  This makes it more clear what is "
  1.5101 +"happening, and reduces the likelihood of a silent and nasty surprise.  This "
  1.5102 +"behaviour is common to most Mercurial commands."
  1.5103 +msgstr ""
  1.5104 +
  1.5105 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5106 +#: ../en/ch05-daily.xml:73
  1.5107 +msgid "Aside: Mercurial tracks files, not directories"
  1.5108 +msgstr "旁白: Mercurial 只跟踪文件，不跟踪目录"
  1.5109 +
  1.5110 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5111 +#: ../en/ch05-daily.xml:75
  1.5112 +msgid ""
  1.5113 +"Mercurial does not track directory information.  Instead, it tracks the path "
  1.5114 +"to a file.  Before creating a file, it first creates any missing directory "
  1.5115 +"components of the path.  After it deletes a file, it then deletes any empty "
  1.5116 +"directories that were in the deleted file's path.  This sounds like a trivial "
  1.5117 +"distinction, but it has one minor practical consequence: it is not possible "
  1.5118 +"to represent a completely empty directory in Mercurial."
  1.5119 +msgstr ""
  1.5120 +
  1.5121 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5122 +#: ../en/ch05-daily.xml:84
  1.5123 +msgid ""
  1.5124 +"Empty directories are rarely useful, and there are unintrusive workarounds "
  1.5125 +"that you can use to achieve an appropriate effect.  The developers of "
  1.5126 +"Mercurial thus felt that the complexity that would be required to manage "
  1.5127 +"empty directories was not worth the limited benefit this feature would bring."
  1.5128 +msgstr ""
  1.5129 +
  1.5130 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5131 +#: ../en/ch05-daily.xml:91
  1.5132 +msgid ""
  1.5133 +"If you need an empty directory in your repository, there are a few ways to "
  1.5134 +"achieve this. One is to create a directory, then <command role=\"hg-cmd\">hg "
  1.5135 +"add</command> a <quote>hidden</quote> file to that directory.  On Unix-like "
  1.5136 +"systems, any file name that begins with a period (<quote><literal>.</"
  1.5137 +"literal></quote>) is treated as hidden by most commands and GUI tools.  This "
  1.5138 +"approach is illustrated below."
  1.5139 +msgstr ""
  1.5140 +
  1.5141 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5142 +#: ../en/ch05-daily.xml:102
  1.5143 +msgid ""
  1.5144 +"Another way to tackle a need for an empty directory is to simply create one "
  1.5145 +"in your automated build scripts before they will need it."
  1.5146 +msgstr ""
  1.5147 +
  1.5148 +#. type: Content of: <book><chapter><sect1><title>
  1.5149 +#: ../en/ch05-daily.xml:109
  1.5150 +msgid "How to stop tracking a file"
  1.5151 +msgstr "如何停止跟踪文件"
  1.5152 +
  1.5153 +#
  1.5154 +#. type: Content of: <book><chapter><sect1><para>
  1.5155 +#: ../en/ch05-daily.xml:111
  1.5156 +msgid ""
  1.5157 +"Once you decide that a file no longer belongs in your repository, use the "
  1.5158 +"<command role=\"hg-cmd\">hg remove</command> command; this deletes the file, "
  1.5159 +"and tells Mercurial to stop tracking it.  A removed file is represented in "
  1.5160 +"the output of <command role=\"hg-cmd\">hg status</command> with a "
  1.5161 +"<quote><literal>R</literal></quote>."
  1.5162 +msgstr ""
  1.5163 +
  1.5164 +#. type: Content of: <book><chapter><sect1><para>
  1.5165 +#: ../en/ch05-daily.xml:120
  1.5166 +msgid ""
  1.5167 +"After you <command role=\"hg-cmd\">hg remove</command> a file, Mercurial will "
  1.5168 +"no longer track changes to that file, even if you recreate a file with the "
  1.5169 +"same name in your working directory.  If you do recreate a file with the same "
  1.5170 +"name and want Mercurial to track the new file, simply <command role=\"hg-cmd"
  1.5171 +"\">hg add</command> it. Mercurial will know that the newly added file is not "
  1.5172 +"related to the old file of the same name."
  1.5173 +msgstr ""
  1.5174 +
  1.5175 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5176 +#: ../en/ch05-daily.xml:129
  1.5177 +msgid "Removing a file does not affect its history"
  1.5178 +msgstr "删除文件不影响历史"
  1.5179 +
  1.5180 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5181 +#: ../en/ch05-daily.xml:131
  1.5182 +msgid "It is important to understand that removing a file has only two effects."
  1.5183 +msgstr ""
  1.5184 +
  1.5185 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.5186 +#: ../en/ch05-daily.xml:134
  1.5187 +msgid "It removes the current version of the file from the working directory."
  1.5188 +msgstr ""
  1.5189 +
  1.5190 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.5191 +#: ../en/ch05-daily.xml:137
  1.5192 +msgid ""
  1.5193 +"It stops Mercurial from tracking changes to the file, from the time of the "
  1.5194 +"next commit."
  1.5195 +msgstr ""
  1.5196 +
  1.5197 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5198 +#: ../en/ch05-daily.xml:140
  1.5199 +msgid ""
  1.5200 +"Removing a file <emphasis>does not</emphasis> in any way alter the "
  1.5201 +"<emphasis>history</emphasis> of the file."
  1.5202 +msgstr ""
  1.5203 +
  1.5204 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5205 +#: ../en/ch05-daily.xml:143
  1.5206 +msgid ""
  1.5207 +"If you update the working directory to a changeset in which a file that you "
  1.5208 +"have removed was still tracked, it will reappear in the working directory, "
  1.5209 +"with the contents it had when you committed that changeset.  If you then "
  1.5210 +"update the working directory to a later changeset, in which the file had been "
  1.5211 +"removed, Mercurial will once again remove the file from the working directory."
  1.5212 +msgstr ""
  1.5213 +
  1.5214 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5215 +#: ../en/ch05-daily.xml:153
  1.5216 +msgid "Missing files"
  1.5217 +msgstr "丢失的文件"
  1.5218 +
  1.5219 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5220 +#: ../en/ch05-daily.xml:155
  1.5221 +msgid ""
  1.5222 +"Mercurial considers a file that you have deleted, but not used <command role="
  1.5223 +"\"hg-cmd\">hg remove</command> to delete, to be <emphasis>missing</"
  1.5224 +"emphasis>.  A missing file is represented with <quote><literal>!</literal></"
  1.5225 +"quote> in the output of <command role=\"hg-cmd\">hg status</command>.  "
  1.5226 +"Mercurial commands will not generally do anything with missing files."
  1.5227 +msgstr ""
  1.5228 +
  1.5229 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5230 +#: ../en/ch05-daily.xml:165
  1.5231 +msgid ""
  1.5232 +"If your repository contains a file that <command role=\"hg-cmd\">hg status</"
  1.5233 +"command> reports as missing, and you want the file to stay gone, you can run "
  1.5234 +"<command role=\"hg-cmd\">hg remove <option role=\"hg-opt-remove\">--after</"
  1.5235 +"option></command> at any time later on, to tell Mercurial that you really did "
  1.5236 +"mean to remove the file."
  1.5237 +msgstr ""
  1.5238 +
  1.5239 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5240 +#: ../en/ch05-daily.xml:175
  1.5241 +msgid ""
  1.5242 +"On the other hand, if you deleted the missing file by accident, give <command "
  1.5243 +"role=\"hg-cmd\">hg revert</command> the name of the file to recover.  It will "
  1.5244 +"reappear, in unmodified form."
  1.5245 +msgstr ""
  1.5246 +
  1.5247 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5248 +#: ../en/ch05-daily.xml:184
  1.5249 +msgid "Aside: why tell Mercurial explicitly to remove a file?"
  1.5250 +msgstr "旁白: 为什么要明确告诉 Mercurial 删除文件?"
  1.5251 +
  1.5252 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5253 +#: ../en/ch05-daily.xml:187
  1.5254 +msgid ""
  1.5255 +"You might wonder why Mercurial requires you to explicitly tell it that you "
  1.5256 +"are deleting a file.  Early during the development of Mercurial, it let you "
  1.5257 +"delete a file however you pleased; Mercurial would notice the absence of the "
  1.5258 +"file automatically when you next ran a <command role=\"hg-cmd\">hg commit</"
  1.5259 +"command>, and stop tracking the file.  In practice, this made it too easy to "
  1.5260 +"accidentally remove a file without noticing."
  1.5261 +msgstr ""
  1.5262 +
  1.5263 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5264 +#: ../en/ch05-daily.xml:198
  1.5265 +msgid "Useful shorthand&emdash;adding and removing files in one step"
  1.5266 +msgstr "有用的速记&emdash;一个步骤添加和删除文件"
  1.5267 +
  1.5268 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5269 +#: ../en/ch05-daily.xml:201
  1.5270 +msgid ""
  1.5271 +"Mercurial offers a combination command, <command role=\"hg-cmd\">hg "
  1.5272 +"addremove</command>, that adds untracked files and marks missing files as "
  1.5273 +"removed."
  1.5274 +msgstr ""
  1.5275 +
  1.5276 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5277 +#: ../en/ch05-daily.xml:207
  1.5278 +msgid ""
  1.5279 +"The <command role=\"hg-cmd\">hg commit</command> command also provides a "
  1.5280 +"<option role=\"hg-opt-commit\">-A</option> option that performs this same add-"
  1.5281 +"and-remove, immediately followed by a commit."
  1.5282 +msgstr ""
  1.5283 +
  1.5284 +#. type: Content of: <book><chapter><sect1><title>
  1.5285 +#: ../en/ch05-daily.xml:217
  1.5286 +msgid "Copying files"
  1.5287 +msgstr "复制文件"
  1.5288 +
  1.5289 +#. type: Content of: <book><chapter><sect1><para>
  1.5290 +#: ../en/ch05-daily.xml:219
  1.5291 +msgid ""
  1.5292 +"Mercurial provides a <command role=\"hg-cmd\">hg copy</command> command that "
  1.5293 +"lets you make a new copy of a file.  When you copy a file using this command, "
  1.5294 +"Mercurial makes a record of the fact that the new file is a copy of the "
  1.5295 +"original file.  It treats these copied files specially when you merge your "
  1.5296 +"work with someone else's."
  1.5297 +msgstr ""
  1.5298 +
  1.5299 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5300 +#: ../en/ch05-daily.xml:227
  1.5301 +msgid "The results of copying during a merge"
  1.5302 +msgstr "合并期间的复制结果"
  1.5303 +
  1.5304 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5305 +#: ../en/ch05-daily.xml:229
  1.5306 +msgid ""
  1.5307 +"What happens during a merge is that changes <quote>follow</quote> a copy.  To "
  1.5308 +"best illustrate what this means, let's create an example.  We'll start with "
  1.5309 +"the usual tiny repository that contains a single file."
  1.5310 +msgstr ""
  1.5311 +
  1.5312 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5313 +#: ../en/ch05-daily.xml:236
  1.5314 +msgid ""
  1.5315 +"We need to do some work in parallel, so that we'll have something to merge.  "
  1.5316 +"So let's clone our repository."
  1.5317 +msgstr ""
  1.5318 +
  1.5319 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5320 +#: ../en/ch05-daily.xml:242
  1.5321 +msgid ""
  1.5322 +"Back in our initial repository, let's use the <command role=\"hg-cmd\">hg "
  1.5323 +"copy</command> command to make a copy of the first file we created."
  1.5324 +msgstr ""
  1.5325 +
  1.5326 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5327 +#: ../en/ch05-daily.xml:248
  1.5328 +msgid ""
  1.5329 +"If we look at the output of the <command role=\"hg-cmd\">hg status</command> "
  1.5330 +"command afterwards, the copied file looks just like a normal added file."
  1.5331 +msgstr ""
  1.5332 +
  1.5333 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5334 +#: ../en/ch05-daily.xml:254
  1.5335 +msgid ""
  1.5336 +"But if we pass the <option role=\"hg-opt-status\">-C</option> option to "
  1.5337 +"<command role=\"hg-cmd\">hg status</command>, it prints another line of "
  1.5338 +"output: this is the file that our newly-added file was copied <emphasis>from</"
  1.5339 +"emphasis>."
  1.5340 +msgstr ""
  1.5341 +
  1.5342 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5343 +#: ../en/ch05-daily.xml:262
  1.5344 +msgid ""
  1.5345 +"Now, back in the repository we cloned, let's make a change in parallel.  "
  1.5346 +"We'll add a line of content to the original file that we created."
  1.5347 +msgstr ""
  1.5348 +
  1.5349 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5350 +#: ../en/ch05-daily.xml:268
  1.5351 +msgid ""
  1.5352 +"Now we have a modified <filename>file</filename> in this repository.  When we "
  1.5353 +"pull the changes from the first repository, and merge the two heads, "
  1.5354 +"Mercurial will propagate the changes that we made locally to <filename>file</"
  1.5355 +"filename> into its copy, <filename>new-file</filename>."
  1.5356 +msgstr ""
  1.5357 +
  1.5358 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5359 +#: ../en/ch05-daily.xml:278
  1.5360 +msgid "Why should changes follow copies?"
  1.5361 +msgstr "为什么复制后需要后续修改?"
  1.5362 +
  1.5363 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5364 +#: ../en/ch05-daily.xml:280
  1.5365 +msgid ""
  1.5366 +"This behaviour, of changes to a file propagating out to copies of the file, "
  1.5367 +"might seem esoteric, but in most cases it's highly desirable."
  1.5368 +msgstr ""
  1.5369 +
  1.5370 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5371 +#: ../en/ch05-daily.xml:284
  1.5372 +msgid ""
  1.5373 +"First of all, remember that this propagation <emphasis>only</emphasis> "
  1.5374 +"happens when you merge.  So if you <command role=\"hg-cmd\">hg copy</command> "
  1.5375 +"a file, and subsequently modify the original file during the normal course of "
  1.5376 +"your work, nothing will happen."
  1.5377 +msgstr ""
  1.5378 +
  1.5379 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5380 +#: ../en/ch05-daily.xml:290
  1.5381 +msgid ""
  1.5382 +"The second thing to know is that modifications will only propagate across a "
  1.5383 +"copy as long as the repository that you're pulling changes from "
  1.5384 +"<emphasis>doesn't know</emphasis> about the copy."
  1.5385 +msgstr ""
  1.5386 +
  1.5387 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5388 +#: ../en/ch05-daily.xml:295
  1.5389 +msgid ""
  1.5390 +"The reason that Mercurial does this is as follows.  Let's say I make an "
  1.5391 +"important bug fix in a source file, and commit my changes. Meanwhile, you've "
  1.5392 +"decided to <command role=\"hg-cmd\">hg copy</command> the file in your "
  1.5393 +"repository, without knowing about the bug or having seen the fix, and you "
  1.5394 +"have started hacking on your copy of the file."
  1.5395 +msgstr ""
  1.5396 +
  1.5397 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5398 +#: ../en/ch05-daily.xml:302
  1.5399 +msgid ""
  1.5400 +"If you pulled and merged my changes, and Mercurial <emphasis>didn't</"
  1.5401 +"emphasis> propagate changes across copies, your source file would now contain "
  1.5402 +"the bug, and unless you remembered to propagate the bug fix by hand, the bug "
  1.5403 +"would <emphasis>remain</emphasis> in your copy of the file."
  1.5404 +msgstr ""
  1.5405 +
  1.5406 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5407 +#: ../en/ch05-daily.xml:308
  1.5408 +msgid ""
  1.5409 +"By automatically propagating the change that fixed the bug from the original "
  1.5410 +"file to the copy, Mercurial prevents this class of problem. To my knowledge, "
  1.5411 +"Mercurial is the <emphasis>only</emphasis> revision control system that "
  1.5412 +"propagates changes across copies like this."
  1.5413 +msgstr ""
  1.5414 +
  1.5415 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5416 +#: ../en/ch05-daily.xml:314
  1.5417 +msgid ""
  1.5418 +"Once your change history has a record that the copy and subsequent merge "
  1.5419 +"occurred, there's usually no further need to propagate changes from the "
  1.5420 +"original file to the copied file, and that's why Mercurial only propagates "
  1.5421 +"changes across copies until this point, and no further."
  1.5422 +msgstr ""
  1.5423 +
  1.5424 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5425 +#: ../en/ch05-daily.xml:322
  1.5426 +msgid "How to make changes <emphasis>not</emphasis> follow a copy"
  1.5427 +msgstr "如何让复制后<emphasis>不</emphasis>修改?"
  1.5428 +
  1.5429 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5430 +#: ../en/ch05-daily.xml:325
  1.5431 +msgid ""
  1.5432 +"If, for some reason, you decide that this business of automatically "
  1.5433 +"propagating changes across copies is not for you, simply use your system's "
  1.5434 +"normal file copy command (on Unix-like systems, that's <command>cp</command>) "
  1.5435 +"to make a copy of a file, then <command role=\"hg-cmd\">hg add</command> the "
  1.5436 +"new copy by hand.  Before you do so, though, please do reread section <xref "
  1.5437 +"linkend=\"sec.daily.why-copy\"/>, and make an informed decision that this "
  1.5438 +"behaviour is not appropriate to your specific case."
  1.5439 +msgstr ""
  1.5440 +
  1.5441 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5442 +#: ../en/ch05-daily.xml:338
  1.5443 +msgid "Behaviour of the <command role=\"hg-cmd\">hg copy</command> command"
  1.5444 +msgstr "命令 <command role=\"hg-cmd\">hg copy</command> 的特性"
  1.5445 +
  1.5446 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5447 +#: ../en/ch05-daily.xml:341
  1.5448 +msgid ""
  1.5449 +"When you use the <command role=\"hg-cmd\">hg copy</command> command, "
  1.5450 +"Mercurial makes a copy of each source file as it currently stands in the "
  1.5451 +"working directory.  This means that if you make some modifications to a file, "
  1.5452 +"then <command role=\"hg-cmd\">hg copy</command> it without first having "
  1.5453 +"committed those changes, the new copy will also contain the modifications you "
  1.5454 +"have made up until that point.  (I find this behaviour a little "
  1.5455 +"counterintuitive, which is why I mention it here.)"
  1.5456 +msgstr ""
  1.5457 +
  1.5458 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5459 +#: ../en/ch05-daily.xml:351
  1.5460 +msgid ""
  1.5461 +"The <command role=\"hg-cmd\">hg copy</command> command acts similarly to the "
  1.5462 +"Unix <command>cp</command> command (you can use the <command role=\"hg-cmd"
  1.5463 +"\">hg cp</command> alias if you prefer).  The last argument is the "
  1.5464 +"<emphasis>destination</emphasis>, and all prior arguments are "
  1.5465 +"<emphasis>sources</emphasis>.  If you pass it a single file as the source, "
  1.5466 +"and the destination does not exist, it creates a new file with that name."
  1.5467 +msgstr ""
  1.5468 +
  1.5469 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5470 +#: ../en/ch05-daily.xml:362
  1.5471 +msgid ""
  1.5472 +"If the destination is a directory, Mercurial copies its sources into that "
  1.5473 +"directory."
  1.5474 +msgstr ""
  1.5475 +
  1.5476 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5477 +#: ../en/ch05-daily.xml:367
  1.5478 +msgid ""
  1.5479 +"Copying a directory is recursive, and preserves the directory structure of "
  1.5480 +"the source."
  1.5481 +msgstr ""
  1.5482 +
  1.5483 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5484 +#: ../en/ch05-daily.xml:373
  1.5485 +msgid ""
  1.5486 +"If the source and destination are both directories, the source tree is "
  1.5487 +"recreated in the destination directory."
  1.5488 +msgstr ""
  1.5489 +
  1.5490 +#
  1.5491 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5492 +#: ../en/ch05-daily.xml:378
  1.5493 +msgid ""
  1.5494 +"As with the <command role=\"hg-cmd\">hg rename</command> command, if you copy "
  1.5495 +"a file manually and then want Mercurial to know that you've copied the file, "
  1.5496 +"simply use the <option role=\"hg-opt-copy\">--after</option> option to "
  1.5497 +"<command role=\"hg-cmd\">hg copy</command>."
  1.5498 +msgstr ""
  1.5499 +
  1.5500 +#. type: Content of: <book><chapter><sect1><title>
  1.5501 +#: ../en/ch05-daily.xml:389
  1.5502 +msgid "Renaming files"
  1.5503 +msgstr "改名文件"
  1.5504 +
  1.5505 +#. type: Content of: <book><chapter><sect1><para>
  1.5506 +#: ../en/ch05-daily.xml:391
  1.5507 +msgid ""
  1.5508 +"It's rather more common to need to rename a file than to make a copy of it.  "
  1.5509 +"The reason I discussed the <command role=\"hg-cmd\">hg copy</command> command "
  1.5510 +"before talking about renaming files is that Mercurial treats a rename in "
  1.5511 +"essentially the same way as a copy.  Therefore, knowing what Mercurial does "
  1.5512 +"when you copy a file tells you what to expect when you rename a file."
  1.5513 +msgstr ""
  1.5514 +
  1.5515 +#. type: Content of: <book><chapter><sect1><para>
  1.5516 +#: ../en/ch05-daily.xml:399
  1.5517 +msgid ""
  1.5518 +"When you use the <command role=\"hg-cmd\">hg rename</command> command, "
  1.5519 +"Mercurial makes a copy of each source file, then deletes it and marks the "
  1.5520 +"file as removed."
  1.5521 +msgstr ""
  1.5522 +
  1.5523 +#. type: Content of: <book><chapter><sect1><para>
  1.5524 +#: ../en/ch05-daily.xml:405
  1.5525 +msgid ""
  1.5526 +"The <command role=\"hg-cmd\">hg status</command> command shows the newly "
  1.5527 +"copied file as added, and the copied-from file as removed."
  1.5528 +msgstr ""
  1.5529 +
  1.5530 +#. type: Content of: <book><chapter><sect1><para>
  1.5531 +#: ../en/ch05-daily.xml:411
  1.5532 +msgid ""
  1.5533 +"As with the results of a <command role=\"hg-cmd\">hg copy</command>, we must "
  1.5534 +"use the <option role=\"hg-opt-status\">-C</option> option to <command role="
  1.5535 +"\"hg-cmd\">hg status</command> to see that the added file is really being "
  1.5536 +"tracked by Mercurial as a copy of the original, now removed, file."
  1.5537 +msgstr ""
  1.5538 +
  1.5539 +#. type: Content of: <book><chapter><sect1><para>
  1.5540 +#: ../en/ch05-daily.xml:420
  1.5541 +msgid ""
  1.5542 +"As with <command role=\"hg-cmd\">hg remove</command> and <command role=\"hg-"
  1.5543 +"cmd\">hg copy</command>, you can tell Mercurial about a rename after the fact "
  1.5544 +"using the <option role=\"hg-opt-rename\">--after</option> option.  In most "
  1.5545 +"other respects, the behaviour of the <command role=\"hg-cmd\">hg rename</"
  1.5546 +"command> command, and the options it accepts, are similar to the <command "
  1.5547 +"role=\"hg-cmd\">hg copy</command> command."
  1.5548 +msgstr ""
  1.5549 +
  1.5550 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5551 +#: ../en/ch05-daily.xml:430
  1.5552 +msgid "Renaming files and merging changes"
  1.5553 +msgstr "改名文件与合并修改"
  1.5554 +
  1.5555 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5556 +#: ../en/ch05-daily.xml:432
  1.5557 +msgid ""
  1.5558 +"Since Mercurial's rename is implemented as copy-and-remove, the same "
  1.5559 +"propagation of changes happens when you merge after a rename as after a copy."
  1.5560 +msgstr ""
  1.5561 +
  1.5562 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5563 +#: ../en/ch05-daily.xml:436
  1.5564 +msgid ""
  1.5565 +"If I modify a file, and you rename it to a new name, and then we merge our "
  1.5566 +"respective changes, my modifications to the file under its original name will "
  1.5567 +"be propagated into the file under its new name. (This is something you might "
  1.5568 +"expect to <quote>simply work,</quote> but not all revision control systems "
  1.5569 +"actually do this.)"
  1.5570 +msgstr ""
  1.5571 +
  1.5572 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5573 +#: ../en/ch05-daily.xml:443
  1.5574 +msgid ""
  1.5575 +"Whereas having changes follow a copy is a feature where you can perhaps nod "
  1.5576 +"and say <quote>yes, that might be useful,</quote> it should be clear that "
  1.5577 +"having them follow a rename is definitely important.  Without this facility, "
  1.5578 +"it would simply be too easy for changes to become orphaned when files are "
  1.5579 +"renamed."
  1.5580 +msgstr ""
  1.5581 +
  1.5582 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5583 +#: ../en/ch05-daily.xml:452
  1.5584 +msgid "Divergent renames and merging"
  1.5585 +msgstr "改名与合并的分歧"
  1.5586 +
  1.5587 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5588 +#: ../en/ch05-daily.xml:454
  1.5589 +msgid ""
  1.5590 +"The case of diverging names occurs when two developers start with a "
  1.5591 +"file&emdash;let's call it <filename>foo</filename>&emdash;in their respective "
  1.5592 +"repositories."
  1.5593 +msgstr ""
  1.5594 +
  1.5595 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5596 +#: ../en/ch05-daily.xml:461
  1.5597 +msgid "Anne renames the file to <filename>bar</filename>."
  1.5598 +msgstr ""
  1.5599 +
  1.5600 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5601 +#: ../en/ch05-daily.xml:465
  1.5602 +msgid "Meanwhile, Bob renames it to <filename>quux</filename>."
  1.5603 +msgstr ""
  1.5604 +
  1.5605 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5606 +#: ../en/ch05-daily.xml:470
  1.5607 +msgid ""
  1.5608 +"I like to think of this as a conflict because each developer has expressed "
  1.5609 +"different intentions about what the file ought to be named."
  1.5610 +msgstr ""
  1.5611 +
  1.5612 +#
  1.5613 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5614 +#: ../en/ch05-daily.xml:474
  1.5615 +msgid ""
  1.5616 +"What do you think should happen when they merge their work? Mercurial's "
  1.5617 +"actual behaviour is that it always preserves <emphasis>both</emphasis> names "
  1.5618 +"when it merges changesets that contain divergent renames."
  1.5619 +msgstr ""
  1.5620 +
  1.5621 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5622 +#: ../en/ch05-daily.xml:481
  1.5623 +msgid ""
  1.5624 +"Notice that Mercurial does warn about the divergent renames, but it leaves it "
  1.5625 +"up to you to do something about the divergence after the merge."
  1.5626 +msgstr ""
  1.5627 +
  1.5628 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5629 +#: ../en/ch05-daily.xml:487
  1.5630 +msgid "Convergent renames and merging"
  1.5631 +msgstr "收敛改名与合并"
  1.5632 +
  1.5633 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5634 +#: ../en/ch05-daily.xml:489
  1.5635 +msgid ""
  1.5636 +"Another kind of rename conflict occurs when two people choose to rename "
  1.5637 +"different <emphasis>source</emphasis> files to the same "
  1.5638 +"<emphasis>destination</emphasis>. In this case, Mercurial runs its normal "
  1.5639 +"merge machinery, and lets you guide it to a suitable resolution."
  1.5640 +msgstr ""
  1.5641 +
  1.5642 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5643 +#: ../en/ch05-daily.xml:497
  1.5644 +msgid "Other name-related corner cases"
  1.5645 +msgstr "其它名称相关的角落"
  1.5646 +
  1.5647 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5648 +#: ../en/ch05-daily.xml:499
  1.5649 +msgid ""
  1.5650 +"Mercurial has a longstanding bug in which it fails to handle a merge where "
  1.5651 +"one side has a file with a given name, while another has a directory with the "
  1.5652 +"same name.  This is documented as <ulink role=\"hg-bug\" url=\"http://www."
  1.5653 +"selenic.com/mercurial/bts/issue29\">issue 29</ulink>."
  1.5654 +msgstr ""
  1.5655 +
  1.5656 +#. type: Content of: <book><chapter><sect1><title>
  1.5657 +#: ../en/ch05-daily.xml:511
  1.5658 +msgid "Recovering from mistakes"
  1.5659 +msgstr "从错误恢复"
  1.5660 +
  1.5661 +#. type: Content of: <book><chapter><sect1><para>
  1.5662 +#: ../en/ch05-daily.xml:513
  1.5663 +msgid ""
  1.5664 +"Mercurial has some useful commands that will help you to recover from some "
  1.5665 +"common mistakes."
  1.5666 +msgstr ""
  1.5667 +
  1.5668 +#. type: Content of: <book><chapter><sect1><para>
  1.5669 +#: ../en/ch05-daily.xml:516
  1.5670 +msgid ""
  1.5671 +"The <command role=\"hg-cmd\">hg revert</command> command lets you undo "
  1.5672 +"changes that you have made to your working directory.  For example, if you "
  1.5673 +"<command role=\"hg-cmd\">hg add</command> a file by accident, just run "
  1.5674 +"<command role=\"hg-cmd\">hg revert</command> with the name of the file you "
  1.5675 +"added, and while the file won't be touched in any way, it won't be tracked "
  1.5676 +"for adding by Mercurial any longer, either.  You can also use <command role="
  1.5677 +"\"hg-cmd\">hg revert</command> to get rid of erroneous changes to a file."
  1.5678 +msgstr ""
  1.5679 +
  1.5680 +#. type: Content of: <book><chapter><sect1><para>
  1.5681 +#: ../en/ch05-daily.xml:526
  1.5682 +msgid ""
  1.5683 +"It's useful to remember that the <command role=\"hg-cmd\">hg revert</command> "
  1.5684 +"command is useful for changes that you have not yet committed.  Once you've "
  1.5685 +"committed a change, if you decide it was a mistake, you can still do "
  1.5686 +"something about it, though your options may be more limited."
  1.5687 +msgstr ""
  1.5688 +
  1.5689 +#. type: Content of: <book><chapter><sect1><para>
  1.5690 +#: ../en/ch05-daily.xml:532
  1.5691 +msgid ""
  1.5692 +"For more information about the <command role=\"hg-cmd\">hg revert</command> "
  1.5693 +"command, and details about how to deal with changes you have already "
  1.5694 +"committed, see chapter <xref linkend=\"chap.undo\"/>."
  1.5695 +msgstr ""
  1.5696 +
  1.5697 +#. type: Content of: <book><chapter><title>
  1.5698 +#: ../en/ch06-collab.xml:5
  1.5699 +msgid "Collaborating with other people"
  1.5700 +msgstr "团体协作"
  1.5701 +
  1.5702 +#. type: Content of: <book><chapter><para>
  1.5703 +#: ../en/ch06-collab.xml:7
  1.5704 +msgid ""
  1.5705 +"As a completely decentralised tool, Mercurial doesn't impose any policy on "
  1.5706 +"how people ought to work with each other.  However, if you're new to "
  1.5707 +"distributed revision control, it helps to have some tools and examples in "
  1.5708 +"mind when you're thinking about possible workflow models."
  1.5709 +msgstr ""
  1.5710 +
  1.5711 +#. type: Content of: <book><chapter><sect1><title>
  1.5712 +#: ../en/ch06-collab.xml:14
  1.5713 +msgid "Mercurial's web interface"
  1.5714 +msgstr ""
  1.5715 +
  1.5716 +#. type: Content of: <book><chapter><sect1><para>
  1.5717 +#: ../en/ch06-collab.xml:16
  1.5718 +msgid ""
  1.5719 +"Mercurial has a powerful web interface that provides several useful "
  1.5720 +"capabilities."
  1.5721 +msgstr ""
  1.5722 +
  1.5723 +#. type: Content of: <book><chapter><sect1><para>
  1.5724 +#: ../en/ch06-collab.xml:19
  1.5725 +msgid ""
  1.5726 +"For interactive use, the web interface lets you browse a single repository or "
  1.5727 +"a collection of repositories.  You can view the history of a repository, "
  1.5728 +"examine each change (comments and diffs), and view the contents of each "
  1.5729 +"directory and file."
  1.5730 +msgstr ""
  1.5731 +
  1.5732 +#. type: Content of: <book><chapter><sect1><para>
  1.5733 +#: ../en/ch06-collab.xml:24
  1.5734 +msgid ""
  1.5735 +"Also for human consumption, the web interface provides an RSS feed of the "
  1.5736 +"changes in a repository.  This lets you <quote>subscribe</quote> to a "
  1.5737 +"repository using your favourite feed reader, and be automatically notified of "
  1.5738 +"activity in that repository as soon as it happens.  I find this capability "
  1.5739 +"much more convenient than the model of subscribing to a mailing list to which "
  1.5740 +"notifications are sent, as it requires no additional configuration on the "
  1.5741 +"part of whoever is serving the repository."
  1.5742 +msgstr ""
  1.5743 +
  1.5744 +#. type: Content of: <book><chapter><sect1><para>
  1.5745 +#: ../en/ch06-collab.xml:34
  1.5746 +msgid ""
  1.5747 +"The web interface also lets remote users clone a repository, pull changes "
  1.5748 +"from it, and (when the server is configured to permit it) push changes back "
  1.5749 +"to it.  Mercurial's HTTP tunneling protocol aggressively compresses data, so "
  1.5750 +"that it works efficiently even over low-bandwidth network connections."
  1.5751 +msgstr ""
  1.5752 +
  1.5753 +#. type: Content of: <book><chapter><sect1><para>
  1.5754 +#: ../en/ch06-collab.xml:40
  1.5755 +msgid ""
  1.5756 +"The easiest way to get started with the web interface is to use your web "
  1.5757 +"browser to visit an existing repository, such as the master Mercurial "
  1.5758 +"repository at <ulink url=\"http://www.selenic.com/repo/hg?style=gitweb"
  1.5759 +"\">http://www.selenic.com/repo/hg?style=gitweb</ulink>."
  1.5760 +msgstr ""
  1.5761 +
  1.5762 +#. type: Content of: <book><chapter><sect1><para>
  1.5763 +#: ../en/ch06-collab.xml:45
  1.5764 +msgid ""
  1.5765 +"If you're interested in providing a web interface to your own repositories, "
  1.5766 +"Mercurial provides two ways to do this.  The first is using the <command role="
  1.5767 +"\"hg-cmd\">hg serve</command> command, which is best suited to short-term "
  1.5768 +"<quote>lightweight</quote> serving.  See section <xref linkend=\"sec.collab."
  1.5769 +"serve\"/> below for details of how to use this command.  If you have a long-"
  1.5770 +"lived repository that you'd like to make permanently available, Mercurial has "
  1.5771 +"built-in support for the CGI (Common Gateway Interface) standard, which all "
  1.5772 +"common web servers support.  See section <xref linkend=\"sec.collab.cgi\"/> "
  1.5773 +"for details of CGI configuration."
  1.5774 +msgstr ""
  1.5775 +
  1.5776 +#. type: Content of: <book><chapter><sect1><title>
  1.5777 +#: ../en/ch06-collab.xml:60
  1.5778 +msgid "Collaboration models"
  1.5779 +msgstr ""
  1.5780 +
  1.5781 +#. type: Content of: <book><chapter><sect1><para>
  1.5782 +#: ../en/ch06-collab.xml:62
  1.5783 +msgid ""
  1.5784 +"With a suitably flexible tool, making decisions about workflow is much more "
  1.5785 +"of a social engineering challenge than a technical one. Mercurial imposes few "
  1.5786 +"limitations on how you can structure the flow of work in a project, so it's "
  1.5787 +"up to you and your group to set up and live with a model that matches your "
  1.5788 +"own particular needs."
  1.5789 +msgstr ""
  1.5790 +
  1.5791 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5792 +#: ../en/ch06-collab.xml:70
  1.5793 +msgid "Factors to keep in mind"
  1.5794 +msgstr ""
  1.5795 +
  1.5796 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5797 +#: ../en/ch06-collab.xml:72
  1.5798 +msgid ""
  1.5799 +"The most important aspect of any model that you must keep in mind is how well "
  1.5800 +"it matches the needs and capabilities of the people who will be using it.  "
  1.5801 +"This might seem self-evident; even so, you still can't afford to forget it "
  1.5802 +"for a moment."
  1.5803 +msgstr ""
  1.5804 +
  1.5805 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5806 +#: ../en/ch06-collab.xml:78
  1.5807 +msgid ""
  1.5808 +"I once put together a workflow model that seemed to make perfect sense to me, "
  1.5809 +"but that caused a considerable amount of consternation and strife within my "
  1.5810 +"development team.  In spite of my attempts to explain why we needed a complex "
  1.5811 +"set of branches, and how changes ought to flow between them, a few team "
  1.5812 +"members revolted.  Even though they were smart people, they didn't want to "
  1.5813 +"pay attention to the constraints we were operating under, or face the "
  1.5814 +"consequences of those constraints in the details of the model that I was "
  1.5815 +"advocating."
  1.5816 +msgstr ""
  1.5817 +
  1.5818 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5819 +#: ../en/ch06-collab.xml:88
  1.5820 +msgid ""
  1.5821 +"Don't sweep foreseeable social or technical problems under the rug. Whatever "
  1.5822 +"scheme you put into effect, you should plan for mistakes and problem "
  1.5823 +"scenarios.  Consider adding automated machinery to prevent, or quickly "
  1.5824 +"recover from, trouble that you can anticipate.  As an example, if you intend "
  1.5825 +"to have a branch with not-for-release changes in it, you'd do well to think "
  1.5826 +"early about the possibility that someone might accidentally merge those "
  1.5827 +"changes into a release branch.  You could avoid this particular problem by "
  1.5828 +"writing a hook that prevents changes from being merged from an inappropriate "
  1.5829 +"branch."
  1.5830 +msgstr ""
  1.5831 +
  1.5832 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5833 +#: ../en/ch06-collab.xml:102
  1.5834 +msgid "Informal anarchy"
  1.5835 +msgstr ""
  1.5836 +
  1.5837 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5838 +#: ../en/ch06-collab.xml:104
  1.5839 +msgid ""
  1.5840 +"I wouldn't suggest an <quote>anything goes</quote> approach as something "
  1.5841 +"sustainable, but it's a model that's easy to grasp, and it works perfectly "
  1.5842 +"well in a few unusual situations."
  1.5843 +msgstr ""
  1.5844 +
  1.5845 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5846 +#: ../en/ch06-collab.xml:109
  1.5847 +msgid ""
  1.5848 +"As one example, many projects have a loose-knit group of collaborators who "
  1.5849 +"rarely physically meet each other.  Some groups like to overcome the "
  1.5850 +"isolation of working at a distance by organising occasional <quote>sprints</"
  1.5851 +"quote>.  In a sprint, a number of people get together in a single location (a "
  1.5852 +"company's conference room, a hotel meeting room, that kind of place) and "
  1.5853 +"spend several days more or less locked in there, hacking intensely on a "
  1.5854 +"handful of projects."
  1.5855 +msgstr ""
  1.5856 +
  1.5857 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5858 +#: ../en/ch06-collab.xml:118
  1.5859 +msgid ""
  1.5860 +"A sprint is the perfect place to use the <command role=\"hg-cmd\">hg serve</"
  1.5861 +"command> command, since <command role=\"hg-cmd\">hg serve</command> does not "
  1.5862 +"require any fancy server infrastructure.  You can get started with <command "
  1.5863 +"role=\"hg-cmd\">hg serve</command> in moments, by reading section <xref "
  1.5864 +"linkend=\"sec.collab.serve\"/> below.  Then simply tell the person next to "
  1.5865 +"you that you're running a server, send the URL to them in an instant message, "
  1.5866 +"and you immediately have a quick-turnaround way to work together.  They can "
  1.5867 +"type your URL into their web browser and quickly review your changes; or they "
  1.5868 +"can pull a bugfix from you and verify it; or they can clone a branch "
  1.5869 +"containing a new feature and try it out."
  1.5870 +msgstr ""
  1.5871 +
  1.5872 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5873 +#: ../en/ch06-collab.xml:132
  1.5874 +msgid ""
  1.5875 +"The charm, and the problem, with doing things in an ad hoc fashion like this "
  1.5876 +"is that only people who know about your changes, and where they are, can see "
  1.5877 +"them.  Such an informal approach simply doesn't scale beyond a handful "
  1.5878 +"people, because each individual needs to know about $n$ different "
  1.5879 +"repositories to pull from."
  1.5880 +msgstr ""
  1.5881 +
  1.5882 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5883 +#: ../en/ch06-collab.xml:141
  1.5884 +msgid "A single central repository"
  1.5885 +msgstr ""
  1.5886 +
  1.5887 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5888 +#: ../en/ch06-collab.xml:143
  1.5889 +msgid ""
  1.5890 +"For smaller projects migrating from a centralised revision control tool, "
  1.5891 +"perhaps the easiest way to get started is to have changes flow through a "
  1.5892 +"single shared central repository.  This is also the most common "
  1.5893 +"<quote>building block</quote> for more ambitious workflow schemes."
  1.5894 +msgstr ""
  1.5895 +
  1.5896 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5897 +#: ../en/ch06-collab.xml:149
  1.5898 +msgid ""
  1.5899 +"Contributors start by cloning a copy of this repository.  They can pull "
  1.5900 +"changes from it whenever they need to, and some (perhaps all) developers have "
  1.5901 +"permission to push a change back when they're ready for other people to see "
  1.5902 +"it."
  1.5903 +msgstr ""
  1.5904 +
  1.5905 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5906 +#: ../en/ch06-collab.xml:154
  1.5907 +msgid ""
  1.5908 +"Under this model, it can still often make sense for people to pull changes "
  1.5909 +"directly from each other, without going through the central repository.  "
  1.5910 +"Consider a case in which I have a tentative bug fix, but I am worried that if "
  1.5911 +"I were to publish it to the central repository, it might subsequently break "
  1.5912 +"everyone else's trees as they pull it.  To reduce the potential for damage, I "
  1.5913 +"can ask you to clone my repository into a temporary repository of your own "
  1.5914 +"and test it.  This lets us put off publishing the potentially unsafe change "
  1.5915 +"until it has had a little testing."
  1.5916 +msgstr ""
  1.5917 +
  1.5918 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5919 +#: ../en/ch06-collab.xml:165
  1.5920 +msgid ""
  1.5921 +"In this kind of scenario, people usually use the <command>ssh</command> "
  1.5922 +"protocol to securely push changes to the central repository, as documented in "
  1.5923 +"section <xref linkend=\"sec.collab.ssh\"/>.  It's also usual to publish a "
  1.5924 +"read-only copy of the repository over HTTP using CGI, as in section <xref "
  1.5925 +"linkend=\"sec.collab.cgi\"/>.  Publishing over HTTP satisfies the needs of "
  1.5926 +"people who don't have push access, and those who want to use web browsers to "
  1.5927 +"browse the repository's history."
  1.5928 +msgstr ""
  1.5929 +
  1.5930 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.5931 +#: ../en/ch06-collab.xml:178
  1.5932 +msgid "Working with multiple branches"
  1.5933 +msgstr ""
  1.5934 +
  1.5935 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5936 +#: ../en/ch06-collab.xml:180
  1.5937 +msgid ""
  1.5938 +"Projects of any significant size naturally tend to make progress on several "
  1.5939 +"fronts simultaneously.  In the case of software, it's common for a project to "
  1.5940 +"go through periodic official releases.  A release might then go into "
  1.5941 +"<quote>maintenance mode</quote> for a while after its first publication; "
  1.5942 +"maintenance releases tend to contain only bug fixes, not new features.  In "
  1.5943 +"parallel with these maintenance releases, one or more future releases may be "
  1.5944 +"under development.  People normally use the word <quote>branch</quote> to "
  1.5945 +"refer to one of these many slightly different directions in which development "
  1.5946 +"is proceeding."
  1.5947 +msgstr ""
  1.5948 +
  1.5949 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5950 +#: ../en/ch06-collab.xml:193
  1.5951 +msgid ""
  1.5952 +"Mercurial is particularly well suited to managing a number of simultaneous, "
  1.5953 +"but not identical, branches.  Each <quote>development direction</quote> can "
  1.5954 +"live in its own central repository, and you can merge changes from one to "
  1.5955 +"another as the need arises.  Because repositories are independent of each "
  1.5956 +"other, unstable changes in a development branch will never affect a stable "
  1.5957 +"branch unless someone explicitly merges those changes in."
  1.5958 +msgstr ""
  1.5959 +
  1.5960 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5961 +#: ../en/ch06-collab.xml:202
  1.5962 +msgid ""
  1.5963 +"Here's an example of how this can work in practice.  Let's say you have one "
  1.5964 +"<quote>main branch</quote> on a central server."
  1.5965 +msgstr ""
  1.5966 +
  1.5967 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5968 +#: ../en/ch06-collab.xml:208
  1.5969 +msgid "People clone it, make changes locally, test them, and push them back."
  1.5970 +msgstr ""
  1.5971 +
  1.5972 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5973 +#: ../en/ch06-collab.xml:211
  1.5974 +msgid ""
  1.5975 +"Once the main branch reaches a release milestone, you can use the <command "
  1.5976 +"role=\"hg-cmd\">hg tag</command> command to give a permanent name to the "
  1.5977 +"milestone revision."
  1.5978 +msgstr ""
  1.5979 +
  1.5980 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5981 +#: ../en/ch06-collab.xml:217
  1.5982 +msgid "Let's say some ongoing development occurs on the main branch."
  1.5983 +msgstr ""
  1.5984 +
  1.5985 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5986 +#: ../en/ch06-collab.xml:222
  1.5987 +msgid ""
  1.5988 +"Using the tag that was recorded at the milestone, people who clone that "
  1.5989 +"repository at any time in the future can use <command role=\"hg-cmd\">hg "
  1.5990 +"update</command> to get a copy of the working directory exactly as it was "
  1.5991 +"when that tagged revision was committed."
  1.5992 +msgstr ""
  1.5993 +
  1.5994 +#
  1.5995 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.5996 +#: ../en/ch06-collab.xml:230
  1.5997 +msgid ""
  1.5998 +"In addition, immediately after the main branch is tagged, someone can then "
  1.5999 +"clone the main branch on the server to a new <quote>stable</quote> branch, "
  1.6000 +"also on the server."
  1.6001 +msgstr ""
  1.6002 +
  1.6003 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6004 +#: ../en/ch06-collab.xml:236
  1.6005 +msgid ""
  1.6006 +"Someone who needs to make a change to the stable branch can then clone "
  1.6007 +"<emphasis>that</emphasis> repository, make their changes, commit, and push "
  1.6008 +"their changes back there."
  1.6009 +msgstr ""
  1.6010 +
  1.6011 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6012 +#: ../en/ch06-collab.xml:242
  1.6013 +msgid ""
  1.6014 +"Because Mercurial repositories are independent, and Mercurial doesn't move "
  1.6015 +"changes around automatically, the stable and main branches are "
  1.6016 +"<emphasis>isolated</emphasis> from each other.  The changes that you made on "
  1.6017 +"the main branch don't <quote>leak</quote> to the stable branch, and vice "
  1.6018 +"versa."
  1.6019 +msgstr ""
  1.6020 +
  1.6021 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6022 +#: ../en/ch06-collab.xml:249
  1.6023 +msgid ""
  1.6024 +"You'll often want all of your bugfixes on the stable branch to show up on the "
  1.6025 +"main branch, too.  Rather than rewrite a bugfix on the main branch, you can "
  1.6026 +"simply pull and merge changes from the stable to the main branch, and "
  1.6027 +"Mercurial will bring those bugfixes in for you."
  1.6028 +msgstr ""
  1.6029 +
  1.6030 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6031 +#: ../en/ch06-collab.xml:257
  1.6032 +msgid ""
  1.6033 +"The main branch will still contain changes that are not on the stable branch, "
  1.6034 +"but it will also contain all of the bugfixes from the stable branch.  The "
  1.6035 +"stable branch remains unaffected by these changes."
  1.6036 +msgstr ""
  1.6037 +
  1.6038 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.6039 +#: ../en/ch06-collab.xml:264 ../en/ch06-collab.xml:276
  1.6040 +msgid "Feature branches"
  1.6041 +msgstr ""
  1.6042 +
  1.6043 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6044 +#: ../en/ch06-collab.xml:266
  1.6045 +msgid ""
  1.6046 +"For larger projects, an effective way to manage change is to break up a team "
  1.6047 +"into smaller groups.  Each group has a shared branch of its own, cloned from "
  1.6048 +"a single <quote>master</quote> branch used by the entire project.  People "
  1.6049 +"working on an individual branch are typically quite isolated from "
  1.6050 +"developments on other branches."
  1.6051 +msgstr ""
  1.6052 +
  1.6053 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.6054 +#: ../en/ch06-collab.xml:274
  1.6055 +msgid ""
  1.6056 +"<imageobject><imagedata fileref=\"images/feature-branches.png\"/></"
  1.6057 +"imageobject>"
  1.6058 +msgstr ""
  1.6059 +
  1.6060 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6061 +#: ../en/ch06-collab.xml:280
  1.6062 +msgid ""
  1.6063 +"When a particular feature is deemed to be in suitable shape, someone on that "
  1.6064 +"feature team pulls and merges from the master branch into the feature branch, "
  1.6065 +"then pushes back up to the master branch."
  1.6066 +msgstr ""
  1.6067 +
  1.6068 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6069 +#: ../en/ch06-collab.xml:287
  1.6070 +msgid "The release train"
  1.6071 +msgstr ""
  1.6072 +
  1.6073 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6074 +#: ../en/ch06-collab.xml:289
  1.6075 +msgid ""
  1.6076 +"Some projects are organised on a <quote>train</quote> basis: a release is "
  1.6077 +"scheduled to happen every few months, and whatever features are ready when "
  1.6078 +"the <quote>train</quote> is ready to leave are allowed in."
  1.6079 +msgstr ""
  1.6080 +
  1.6081 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6082 +#: ../en/ch06-collab.xml:294
  1.6083 +msgid ""
  1.6084 +"This model resembles working with feature branches.  The difference is that "
  1.6085 +"when a feature branch misses a train, someone on the feature team pulls and "
  1.6086 +"merges the changes that went out on that train release into the feature "
  1.6087 +"branch, and the team continues its work on top of that release so that their "
  1.6088 +"feature can make the next release."
  1.6089 +msgstr ""
  1.6090 +
  1.6091 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6092 +#: ../en/ch06-collab.xml:303
  1.6093 +msgid "The Linux kernel model"
  1.6094 +msgstr ""
  1.6095 +
  1.6096 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6097 +#: ../en/ch06-collab.xml:305
  1.6098 +msgid ""
  1.6099 +"The development of the Linux kernel has a shallow hierarchical structure, "
  1.6100 +"surrounded by a cloud of apparent chaos.  Because most Linux developers use "
  1.6101 +"<command>git</command>, a distributed revision control tool with capabilities "
  1.6102 +"similar to Mercurial, it's useful to describe the way work flows in that "
  1.6103 +"environment; if you like the ideas, the approach translates well across tools."
  1.6104 +msgstr ""
  1.6105 +
  1.6106 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6107 +#: ../en/ch06-collab.xml:313
  1.6108 +msgid ""
  1.6109 +"At the center of the community sits Linus Torvalds, the creator of Linux.  He "
  1.6110 +"publishes a single source repository that is considered the "
  1.6111 +"<quote>authoritative</quote> current tree by the entire developer community. "
  1.6112 +"Anyone can clone Linus's tree, but he is very choosy about whose trees he "
  1.6113 +"pulls from."
  1.6114 +msgstr ""
  1.6115 +
  1.6116 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6117 +#: ../en/ch06-collab.xml:320
  1.6118 +msgid ""
  1.6119 +"Linus has a number of <quote>trusted lieutenants</quote>.  As a general rule, "
  1.6120 +"he pulls whatever changes they publish, in most cases without even reviewing "
  1.6121 +"those changes.  Some of those lieutenants are generally agreed to be "
  1.6122 +"<quote>maintainers</quote>, responsible for specific subsystems within the "
  1.6123 +"kernel.  If a random kernel hacker wants to make a change to a subsystem that "
  1.6124 +"they want to end up in Linus's tree, they must find out who the subsystem's "
  1.6125 +"maintainer is, and ask that maintainer to take their change.  If the "
  1.6126 +"maintainer reviews their changes and agrees to take them, they'll pass them "
  1.6127 +"along to Linus in due course."
  1.6128 +msgstr ""
  1.6129 +
  1.6130 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6131 +#: ../en/ch06-collab.xml:332
  1.6132 +msgid ""
  1.6133 +"Individual lieutenants have their own approaches to reviewing, accepting, and "
  1.6134 +"publishing changes; and for deciding when to feed them to Linus.  In "
  1.6135 +"addition, there are several well known branches that people use for different "
  1.6136 +"purposes.  For example, a few people maintain <quote>stable</quote> "
  1.6137 +"repositories of older versions of the kernel, to which they apply critical "
  1.6138 +"fixes as needed.  Some maintainers publish multiple trees: one for "
  1.6139 +"experimental changes; one for changes that they are about to feed upstream; "
  1.6140 +"and so on.  Others just publish a single tree."
  1.6141 +msgstr ""
  1.6142 +
  1.6143 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6144 +#: ../en/ch06-collab.xml:343
  1.6145 +msgid ""
  1.6146 +"This model has two notable features.  The first is that it's <quote>pull "
  1.6147 +"only</quote>.  You have to ask, convince, or beg another developer to take a "
  1.6148 +"change from you, because there are almost no trees to which more than one "
  1.6149 +"person can push, and there's no way to push changes into a tree that someone "
  1.6150 +"else controls."
  1.6151 +msgstr ""
  1.6152 +
  1.6153 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6154 +#: ../en/ch06-collab.xml:350
  1.6155 +msgid ""
  1.6156 +"The second is that it's based on reputation and acclaim.  If you're an "
  1.6157 +"unknown, Linus will probably ignore changes from you without even "
  1.6158 +"responding.  But a subsystem maintainer will probably review them, and will "
  1.6159 +"likely take them if they pass their criteria for suitability. The more "
  1.6160 +"<quote>good</quote> changes you contribute to a maintainer, the more likely "
  1.6161 +"they are to trust your judgment and accept your changes.  If you're well-"
  1.6162 +"known and maintain a long-lived branch for something Linus hasn't yet "
  1.6163 +"accepted, people with similar interests may pull your changes regularly to "
  1.6164 +"keep up with your work."
  1.6165 +msgstr ""
  1.6166 +
  1.6167 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6168 +#: ../en/ch06-collab.xml:361
  1.6169 +msgid ""
  1.6170 +"Reputation and acclaim don't necessarily cross subsystem or <quote>people</"
  1.6171 +"quote> boundaries.  If you're a respected but specialised storage hacker, and "
  1.6172 +"you try to fix a networking bug, that change will receive a level of scrutiny "
  1.6173 +"from a network maintainer comparable to a change from a complete stranger."
  1.6174 +msgstr ""
  1.6175 +
  1.6176 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6177 +#: ../en/ch06-collab.xml:368
  1.6178 +msgid ""
  1.6179 +"To people who come from more orderly project backgrounds, the comparatively "
  1.6180 +"chaotic Linux kernel development process often seems completely insane.  It's "
  1.6181 +"subject to the whims of individuals; people make sweeping changes whenever "
  1.6182 +"they deem it appropriate; and the pace of development is astounding.  And yet "
  1.6183 +"Linux is a highly successful, well-regarded piece of software."
  1.6184 +msgstr ""
  1.6185 +
  1.6186 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6187 +#: ../en/ch06-collab.xml:378
  1.6188 +msgid "Pull-only versus shared-push collaboration"
  1.6189 +msgstr ""
  1.6190 +
  1.6191 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6192 +#: ../en/ch06-collab.xml:380
  1.6193 +msgid ""
  1.6194 +"A perpetual source of heat in the open source community is whether a "
  1.6195 +"development model in which people only ever pull changes from others is "
  1.6196 +"<quote>better than</quote> one in which multiple people can push changes to a "
  1.6197 +"shared repository."
  1.6198 +msgstr ""
  1.6199 +
  1.6200 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6201 +#: ../en/ch06-collab.xml:386
  1.6202 +msgid ""
  1.6203 +"Typically, the backers of the shared-push model use tools that actively "
  1.6204 +"enforce this approach.  If you're using a centralised revision control tool "
  1.6205 +"such as Subversion, there's no way to make a choice over which model you'll "
  1.6206 +"use: the tool gives you shared-push, and if you want to do anything else, "
  1.6207 +"you'll have to roll your own approach on top (such as applying a patch by "
  1.6208 +"hand)."
  1.6209 +msgstr ""
  1.6210 +
  1.6211 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6212 +#: ../en/ch06-collab.xml:394
  1.6213 +msgid ""
  1.6214 +"A good distributed revision control tool, such as Mercurial, will support "
  1.6215 +"both models.  You and your collaborators can then structure how you work "
  1.6216 +"together based on your own needs and preferences, not on what contortions "
  1.6217 +"your tools force you into."
  1.6218 +msgstr ""
  1.6219 +
  1.6220 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6221 +#: ../en/ch06-collab.xml:402
  1.6222 +msgid "Where collaboration meets branch management"
  1.6223 +msgstr ""
  1.6224 +
  1.6225 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6226 +#: ../en/ch06-collab.xml:404
  1.6227 +msgid ""
  1.6228 +"Once you and your team set up some shared repositories and start propagating "
  1.6229 +"changes back and forth between local and shared repos, you begin to face a "
  1.6230 +"related, but slightly different challenge: that of managing the multiple "
  1.6231 +"directions in which your team may be moving at once.  Even though this "
  1.6232 +"subject is intimately related to how your team collaborates, it's dense "
  1.6233 +"enough to merit treatment of its own, in chapter <xref linkend=\"chap.branch"
  1.6234 +"\"/>."
  1.6235 +msgstr ""
  1.6236 +
  1.6237 +#. type: Content of: <book><chapter><sect1><title>
  1.6238 +#: ../en/ch06-collab.xml:416
  1.6239 +msgid "The technical side of sharing"
  1.6240 +msgstr ""
  1.6241 +
  1.6242 +#. type: Content of: <book><chapter><sect1><para>
  1.6243 +#: ../en/ch06-collab.xml:418
  1.6244 +msgid ""
  1.6245 +"The remainder of this chapter is devoted to the question of serving data to "
  1.6246 +"your collaborators."
  1.6247 +msgstr ""
  1.6248 +
  1.6249 +#. type: Content of: <book><chapter><sect1><title>
  1.6250 +#: ../en/ch06-collab.xml:423
  1.6251 +msgid "Informal sharing with <command role=\"hg-cmd\">hg serve</command>"
  1.6252 +msgstr ""
  1.6253 +
  1.6254 +#. type: Content of: <book><chapter><sect1><para>
  1.6255 +#: ../en/ch06-collab.xml:426
  1.6256 +msgid ""
  1.6257 +"Mercurial's <command role=\"hg-cmd\">hg serve</command> command is "
  1.6258 +"wonderfully suited to small, tight-knit, and fast-paced group environments.  "
  1.6259 +"It also provides a great way to get a feel for using Mercurial commands over "
  1.6260 +"a network."
  1.6261 +msgstr ""
  1.6262 +
  1.6263 +#. type: Content of: <book><chapter><sect1><para>
  1.6264 +#: ../en/ch06-collab.xml:431
  1.6265 +msgid ""
  1.6266 +"Run <command role=\"hg-cmd\">hg serve</command> inside a repository, and in "
  1.6267 +"under a second it will bring up a specialised HTTP server; this will accept "
  1.6268 +"connections from any client, and serve up data for that repository until you "
  1.6269 +"terminate it.  Anyone who knows the URL of the server you just started, and "
  1.6270 +"can talk to your computer over the network, can then use a web browser or "
  1.6271 +"Mercurial to read data from that repository.  A URL for a <command role=\"hg-"
  1.6272 +"cmd\">hg serve</command> instance running on a laptop is likely to look "
  1.6273 +"something like <literal>http://my-laptop.local:8000/</literal>."
  1.6274 +msgstr ""
  1.6275 +
  1.6276 +#. type: Content of: <book><chapter><sect1><para>
  1.6277 +#: ../en/ch06-collab.xml:442
  1.6278 +msgid ""
  1.6279 +"The <command role=\"hg-cmd\">hg serve</command> command is <emphasis>not</"
  1.6280 +"emphasis> a general-purpose web server. It can do only two things:"
  1.6281 +msgstr ""
  1.6282 +
  1.6283 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.6284 +#: ../en/ch06-collab.xml:446
  1.6285 +msgid ""
  1.6286 +"Allow people to browse the history of the repository it's serving, from their "
  1.6287 +"normal web browsers."
  1.6288 +msgstr ""
  1.6289 +
  1.6290 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.6291 +#: ../en/ch06-collab.xml:450
  1.6292 +msgid ""
  1.6293 +"Speak Mercurial's wire protocol, so that people can <command role=\"hg-cmd"
  1.6294 +"\">hg clone</command> or <command role=\"hg-cmd\">hg pull</command> changes "
  1.6295 +"from that repository."
  1.6296 +msgstr ""
  1.6297 +
  1.6298 +#. type: Content of: <book><chapter><sect1><para>
  1.6299 +#: ../en/ch06-collab.xml:455
  1.6300 +msgid ""
  1.6301 +"In particular, <command role=\"hg-cmd\">hg serve</command> won't allow remote "
  1.6302 +"users to <emphasis>modify</emphasis> your repository.  It's intended for read-"
  1.6303 +"only use."
  1.6304 +msgstr ""
  1.6305 +
  1.6306 +#. type: Content of: <book><chapter><sect1><para>
  1.6307 +#: ../en/ch06-collab.xml:459
  1.6308 +msgid ""
  1.6309 +"If you're getting started with Mercurial, there's nothing to prevent you from "
  1.6310 +"using <command role=\"hg-cmd\">hg serve</command> to serve up a repository on "
  1.6311 +"your own computer, then use commands like <command role=\"hg-cmd\">hg clone</"
  1.6312 +"command>, <command role=\"hg-cmd\">hg incoming</command>, and so on to talk "
  1.6313 +"to that server as if the repository was hosted remotely. This can help you to "
  1.6314 +"quickly get acquainted with using commands on network-hosted repositories."
  1.6315 +msgstr ""
  1.6316 +
  1.6317 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6318 +#: ../en/ch06-collab.xml:469
  1.6319 +msgid "A few things to keep in mind"
  1.6320 +msgstr ""
  1.6321 +
  1.6322 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6323 +#: ../en/ch06-collab.xml:471
  1.6324 +msgid ""
  1.6325 +"Because it provides unauthenticated read access to all clients, you should "
  1.6326 +"only use <command role=\"hg-cmd\">hg serve</command> in an environment where "
  1.6327 +"you either don't care, or have complete control over, who can access your "
  1.6328 +"network and pull data from your repository."
  1.6329 +msgstr ""
  1.6330 +
  1.6331 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6332 +#: ../en/ch06-collab.xml:477
  1.6333 +msgid ""
  1.6334 +"The <command role=\"hg-cmd\">hg serve</command> command knows nothing about "
  1.6335 +"any firewall software you might have installed on your system or network.  It "
  1.6336 +"cannot detect or control your firewall software.  If other people are unable "
  1.6337 +"to talk to a running <command role=\"hg-cmd\">hg serve</command> instance, "
  1.6338 +"the second thing you should do (<emphasis>after</emphasis> you make sure that "
  1.6339 +"they're using the correct URL) is check your firewall configuration."
  1.6340 +msgstr ""
  1.6341 +
  1.6342 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6343 +#: ../en/ch06-collab.xml:486
  1.6344 +msgid ""
  1.6345 +"By default, <command role=\"hg-cmd\">hg serve</command> listens for incoming "
  1.6346 +"connections on port 8000.  If another process is already listening on the "
  1.6347 +"port you want to use, you can specify a different port to listen on using the "
  1.6348 +"<option role=\"hg-opt-serve\">-p</option> option."
  1.6349 +msgstr ""
  1.6350 +
  1.6351 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6352 +#: ../en/ch06-collab.xml:492
  1.6353 +msgid ""
  1.6354 +"Normally, when <command role=\"hg-cmd\">hg serve</command> starts, it prints "
  1.6355 +"no output, which can be a bit unnerving.  If you'd like to confirm that it is "
  1.6356 +"indeed running correctly, and find out what URL you should send to your "
  1.6357 +"collaborators, start it with the <option role=\"hg-opt-global\">-v</option> "
  1.6358 +"option."
  1.6359 +msgstr ""
  1.6360 +
  1.6361 +#. type: Content of: <book><chapter><sect1><title>
  1.6362 +#: ../en/ch06-collab.xml:502
  1.6363 +msgid "Using the Secure Shell (ssh) protocol"
  1.6364 +msgstr ""
  1.6365 +
  1.6366 +#. type: Content of: <book><chapter><sect1><para>
  1.6367 +#: ../en/ch06-collab.xml:504
  1.6368 +msgid ""
  1.6369 +"You can pull and push changes securely over a network connection using the "
  1.6370 +"Secure Shell (<literal>ssh</literal>)  protocol.  To use this successfully, "
  1.6371 +"you may have to do a little bit of configuration on the client or server "
  1.6372 +"sides."
  1.6373 +msgstr ""
  1.6374 +
  1.6375 +#. type: Content of: <book><chapter><sect1><para>
  1.6376 +#: ../en/ch06-collab.xml:509
  1.6377 +msgid ""
  1.6378 +"If you're not familiar with ssh, it's a network protocol that lets you "
  1.6379 +"securely communicate with another computer.  To use it with Mercurial, you'll "
  1.6380 +"be setting up one or more user accounts on a server so that remote users can "
  1.6381 +"log in and execute commands."
  1.6382 +msgstr ""
  1.6383 +
  1.6384 +#. type: Content of: <book><chapter><sect1><para>
  1.6385 +#: ../en/ch06-collab.xml:515
  1.6386 +msgid ""
  1.6387 +"(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some "
  1.6388 +"of the material that follows to be elementary in nature.)"
  1.6389 +msgstr ""
  1.6390 +
  1.6391 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6392 +#: ../en/ch06-collab.xml:520
  1.6393 +msgid "How to read and write ssh URLs"
  1.6394 +msgstr ""
  1.6395 +
  1.6396 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6397 +#: ../en/ch06-collab.xml:522
  1.6398 +msgid "An ssh URL tends to look like this:"
  1.6399 +msgstr ""
  1.6400 +
  1.6401 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6402 +#: ../en/ch06-collab.xml:525
  1.6403 +msgid ""
  1.6404 +"The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the "
  1.6405 +"ssh protocol."
  1.6406 +msgstr ""
  1.6407 +
  1.6408 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6409 +#: ../en/ch06-collab.xml:528
  1.6410 +msgid ""
  1.6411 +"The <quote><literal>bos@</literal></quote> component indicates what username "
  1.6412 +"to log into the server as.  You can leave this out if the remote username is "
  1.6413 +"the same as your local username."
  1.6414 +msgstr ""
  1.6415 +
  1.6416 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6417 +#: ../en/ch06-collab.xml:533
  1.6418 +msgid ""
  1.6419 +"The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of "
  1.6420 +"the server to log into."
  1.6421 +msgstr ""
  1.6422 +
  1.6423 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6424 +#: ../en/ch06-collab.xml:537
  1.6425 +msgid ""
  1.6426 +"The <quote>:22</quote> identifies the port number to connect to the server "
  1.6427 +"on.  The default port is 22, so you only need to specify this part if you're "
  1.6428 +"<emphasis>not</emphasis> using port 22."
  1.6429 +msgstr ""
  1.6430 +
  1.6431 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6432 +#: ../en/ch06-collab.xml:542
  1.6433 +msgid ""
  1.6434 +"The remainder of the URL is the local path to the repository on the server."
  1.6435 +msgstr ""
  1.6436 +
  1.6437 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6438 +#: ../en/ch06-collab.xml:546
  1.6439 +msgid ""
  1.6440 +"There's plenty of scope for confusion with the path component of ssh URLs, as "
  1.6441 +"there is no standard way for tools to interpret it.  Some programs behave "
  1.6442 +"differently than others when dealing with these paths. This isn't an ideal "
  1.6443 +"situation, but it's unlikely to change.  Please read the following paragraphs "
  1.6444 +"carefully."
  1.6445 +msgstr ""
  1.6446 +
  1.6447 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6448 +#: ../en/ch06-collab.xml:553
  1.6449 +msgid ""
  1.6450 +"Mercurial treats the path to a repository on the server as relative to the "
  1.6451 +"remote user's home directory.  For example, if user <literal>foo</literal> on "
  1.6452 +"the server has a home directory of <filename class=\"directory\">/home/foo</"
  1.6453 +"filename>, then an ssh URL that contains a path component of <filename class="
  1.6454 +"\"directory\">bar</filename> <emphasis>really</emphasis> refers to the "
  1.6455 +"directory <filename class=\"directory\">/home/foo/bar</filename>."
  1.6456 +msgstr ""
  1.6457 +
  1.6458 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6459 +#: ../en/ch06-collab.xml:562
  1.6460 +msgid ""
  1.6461 +"If you want to specify a path relative to another user's home directory, you "
  1.6462 +"can use a path that starts with a tilde character followed by the user's name "
  1.6463 +"(let's call them <literal>otheruser</literal>), like this."
  1.6464 +msgstr ""
  1.6465 +
  1.6466 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6467 +#: ../en/ch06-collab.xml:568
  1.6468 +msgid ""
  1.6469 +"And if you really want to specify an <emphasis>absolute</emphasis> path on "
  1.6470 +"the server, begin the path component with two slashes, as in this example."
  1.6471 +msgstr ""
  1.6472 +
  1.6473 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6474 +#: ../en/ch06-collab.xml:575
  1.6475 +msgid "Finding an ssh client for your system"
  1.6476 +msgstr ""
  1.6477 +
  1.6478 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6479 +#: ../en/ch06-collab.xml:577
  1.6480 +msgid ""
  1.6481 +"Almost every Unix-like system comes with OpenSSH preinstalled.  If you're "
  1.6482 +"using such a system, run <literal>which ssh</literal> to find out if the "
  1.6483 +"<command>ssh</command> command is installed (it's usually in <filename class="
  1.6484 +"\"directory\">/usr/bin</filename>).  In the unlikely event that it isn't "
  1.6485 +"present, take a look at your system documentation to figure out how to "
  1.6486 +"install it."
  1.6487 +msgstr ""
  1.6488 +
  1.6489 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6490 +#: ../en/ch06-collab.xml:585
  1.6491 +msgid ""
  1.6492 +"On Windows, you'll first need to download a suitable ssh client.  There are "
  1.6493 +"two alternatives."
  1.6494 +msgstr ""
  1.6495 +
  1.6496 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6497 +#: ../en/ch06-collab.xml:588
  1.6498 +msgid ""
  1.6499 +"Simon Tatham's excellent PuTTY package <citation>web:putty</citation> "
  1.6500 +"provides a complete suite of ssh client commands."
  1.6501 +msgstr ""
  1.6502 +
  1.6503 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6504 +#: ../en/ch06-collab.xml:592
  1.6505 +msgid ""
  1.6506 +"If you have a high tolerance for pain, you can use the Cygwin port of OpenSSH."
  1.6507 +msgstr ""
  1.6508 +
  1.6509 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6510 +#: ../en/ch06-collab.xml:595
  1.6511 +msgid ""
  1.6512 +"In either case, you'll need to edit your \\hgini\\ file to tell Mercurial "
  1.6513 +"where to find the actual client command.  For example, if you're using PuTTY, "
  1.6514 +"you'll need to use the <command>plink</command> command as a command-line ssh "
  1.6515 +"client."
  1.6516 +msgstr ""
  1.6517 +
  1.6518 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
  1.6519 +#: ../en/ch06-collab.xml:604
  1.6520 +msgid ""
  1.6521 +"The path to <command>plink</command> shouldn't contain any whitespace "
  1.6522 +"characters, or Mercurial may not be able to run it correctly (so putting it "
  1.6523 +"in <filename class=\"directory\">C:\\\\Program Files</filename> is probably "
  1.6524 +"not a good idea)."
  1.6525 +msgstr ""
  1.6526 +
  1.6527 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6528 +#: ../en/ch06-collab.xml:613
  1.6529 +msgid "Generating a key pair"
  1.6530 +msgstr ""
  1.6531 +
  1.6532 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6533 +#: ../en/ch06-collab.xml:615
  1.6534 +msgid ""
  1.6535 +"To avoid the need to repetitively type a password every time you need to use "
  1.6536 +"your ssh client, I recommend generating a key pair.  On a Unix-like system, "
  1.6537 +"the <command>ssh-keygen</command> command will do the trick. On Windows, if "
  1.6538 +"you're using PuTTY, the <command>puttygen</command> command is what you'll "
  1.6539 +"need."
  1.6540 +msgstr ""
  1.6541 +
  1.6542 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6543 +#: ../en/ch06-collab.xml:623
  1.6544 +msgid ""
  1.6545 +"When you generate a key pair, it's usually <emphasis>highly</emphasis> "
  1.6546 +"advisable to protect it with a passphrase.  (The only time that you might not "
  1.6547 +"want to do this is when you're using the ssh protocol for automated tasks on "
  1.6548 +"a secure network.)"
  1.6549 +msgstr ""
  1.6550 +
  1.6551 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6552 +#: ../en/ch06-collab.xml:629
  1.6553 +msgid ""
  1.6554 +"Simply generating a key pair isn't enough, however.  You'll need to add the "
  1.6555 +"public key to the set of authorised keys for whatever user you're logging in "
  1.6556 +"remotely as.  For servers using OpenSSH (the vast majority), this will mean "
  1.6557 +"adding the public key to a list in a file called <filename role=\"special"
  1.6558 +"\">authorized_keys</filename> in their <filename role=\"special\" class="
  1.6559 +"\"directory\">.ssh</filename> directory."
  1.6560 +msgstr ""
  1.6561 +
  1.6562 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6563 +#: ../en/ch06-collab.xml:638
  1.6564 +msgid ""
  1.6565 +"On a Unix-like system, your public key will have a <filename>.pub</filename> "
  1.6566 +"extension.  If you're using <command>puttygen</command> on Windows, you can "
  1.6567 +"save the public key to a file of your choosing, or paste it from the window "
  1.6568 +"it's displayed in straight into the <filename role=\"special"
  1.6569 +"\">authorized_keys</filename> file."
  1.6570 +msgstr ""
  1.6571 +
  1.6572 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6573 +#: ../en/ch06-collab.xml:647
  1.6574 +msgid "Using an authentication agent"
  1.6575 +msgstr ""
  1.6576 +
  1.6577 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6578 +#: ../en/ch06-collab.xml:649
  1.6579 +msgid ""
  1.6580 +"An authentication agent is a daemon that stores passphrases in memory (so it "
  1.6581 +"will forget passphrases if you log out and log back in again). An ssh client "
  1.6582 +"will notice if it's running, and query it for a passphrase.  If there's no "
  1.6583 +"authentication agent running, or the agent doesn't store the necessary "
  1.6584 +"passphrase, you'll have to type your passphrase every time Mercurial tries to "
  1.6585 +"communicate with a server on your behalf (e.g. whenever you pull or push "
  1.6586 +"changes)."
  1.6587 +msgstr ""
  1.6588 +
  1.6589 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6590 +#: ../en/ch06-collab.xml:658
  1.6591 +msgid ""
  1.6592 +"The downside of storing passphrases in an agent is that it's possible for a "
  1.6593 +"well-prepared attacker to recover the plain text of your passphrases, in some "
  1.6594 +"cases even if your system has been power-cycled. You should make your own "
  1.6595 +"judgment as to whether this is an acceptable risk.  It certainly saves a lot "
  1.6596 +"of repeated typing."
  1.6597 +msgstr ""
  1.6598 +
  1.6599 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6600 +#: ../en/ch06-collab.xml:665
  1.6601 +msgid ""
  1.6602 +"On Unix-like systems, the agent is called <command>ssh-agent</command>, and "
  1.6603 +"it's often run automatically for you when you log in.  You'll need to use the "
  1.6604 +"<command>ssh-add</command> command to add passphrases to the agent's store.  "
  1.6605 +"On Windows, if you're using PuTTY, the <command>pageant</command> command "
  1.6606 +"acts as the agent.  It adds an icon to your system tray that will let you "
  1.6607 +"manage stored passphrases."
  1.6608 +msgstr ""
  1.6609 +
  1.6610 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6611 +#: ../en/ch06-collab.xml:676
  1.6612 +msgid "Configuring the server side properly"
  1.6613 +msgstr ""
  1.6614 +
  1.6615 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6616 +#: ../en/ch06-collab.xml:678
  1.6617 +msgid ""
  1.6618 +"Because ssh can be fiddly to set up if you're new to it, there's a variety of "
  1.6619 +"things that can go wrong.  Add Mercurial on top, and there's plenty more "
  1.6620 +"scope for head-scratching.  Most of these potential problems occur on the "
  1.6621 +"server side, not the client side.  The good news is that once you've gotten a "
  1.6622 +"configuration working, it will usually continue to work indefinitely."
  1.6623 +msgstr ""
  1.6624 +
  1.6625 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6626 +#: ../en/ch06-collab.xml:686
  1.6627 +msgid ""
  1.6628 +"Before you try using Mercurial to talk to an ssh server, it's best to make "
  1.6629 +"sure that you can use the normal <command>ssh</command> or <command>putty</"
  1.6630 +"command> command to talk to the server first.  If you run into problems with "
  1.6631 +"using these commands directly, Mercurial surely won't work.  Worse, it will "
  1.6632 +"obscure the underlying problem.  Any time you want to debug ssh-related "
  1.6633 +"Mercurial problems, you should drop back to making sure that plain ssh client "
  1.6634 +"commands work first, <emphasis>before</emphasis> you worry about whether "
  1.6635 +"there's a problem with Mercurial."
  1.6636 +msgstr ""
  1.6637 +
  1.6638 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6639 +#: ../en/ch06-collab.xml:697
  1.6640 +msgid ""
  1.6641 +"The first thing to be sure of on the server side is that you can actually log "
  1.6642 +"in from another machine at all.  If you can't use <command>ssh</command> or "
  1.6643 +"<command>putty</command> to log in, the error message you get may give you a "
  1.6644 +"few hints as to what's wrong.  The most common problems are as follows."
  1.6645 +msgstr ""
  1.6646 +
  1.6647 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6648 +#: ../en/ch06-collab.xml:704
  1.6649 +msgid ""
  1.6650 +"If you get a <quote>connection refused</quote> error, either there isn't an "
  1.6651 +"SSH daemon running on the server at all, or it's inaccessible due to firewall "
  1.6652 +"configuration."
  1.6653 +msgstr ""
  1.6654 +
  1.6655 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6656 +#: ../en/ch06-collab.xml:709
  1.6657 +msgid ""
  1.6658 +"If you get a <quote>no route to host</quote> error, you either have an "
  1.6659 +"incorrect address for the server or a seriously locked down firewall that "
  1.6660 +"won't admit its existence at all."
  1.6661 +msgstr ""
  1.6662 +
  1.6663 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6664 +#: ../en/ch06-collab.xml:714
  1.6665 +msgid ""
  1.6666 +"If you get a <quote>permission denied</quote> error, you may have mistyped "
  1.6667 +"the username on the server, or you could have mistyped your key's passphrase "
  1.6668 +"or the remote user's password."
  1.6669 +msgstr ""
  1.6670 +
  1.6671 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6672 +#: ../en/ch06-collab.xml:719
  1.6673 +msgid ""
  1.6674 +"In summary, if you're having trouble talking to the server's ssh daemon, "
  1.6675 +"first make sure that one is running at all.  On many systems it will be "
  1.6676 +"installed, but disabled, by default.  Once you're done with this step, you "
  1.6677 +"should then check that the server's firewall is configured to allow incoming "
  1.6678 +"connections on the port the ssh daemon is listening on (usually 22).  Don't "
  1.6679 +"worry about more exotic possibilities for misconfiguration until you've "
  1.6680 +"checked these two first."
  1.6681 +msgstr ""
  1.6682 +
  1.6683 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6684 +#: ../en/ch06-collab.xml:729
  1.6685 +msgid ""
  1.6686 +"If you're using an authentication agent on the client side to store "
  1.6687 +"passphrases for your keys, you ought to be able to log into the server "
  1.6688 +"without being prompted for a passphrase or a password.  If you're prompted "
  1.6689 +"for a passphrase, there are a few possible culprits."
  1.6690 +msgstr ""
  1.6691 +
  1.6692 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6693 +#: ../en/ch06-collab.xml:735
  1.6694 +msgid ""
  1.6695 +"You might have forgotten to use <command>ssh-add</command> or "
  1.6696 +"<command>pageant</command> to store the passphrase."
  1.6697 +msgstr ""
  1.6698 +
  1.6699 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6700 +#: ../en/ch06-collab.xml:739
  1.6701 +msgid "You might have stored the passphrase for the wrong key."
  1.6702 +msgstr ""
  1.6703 +
  1.6704 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6705 +#: ../en/ch06-collab.xml:742
  1.6706 +msgid ""
  1.6707 +"If you're being prompted for the remote user's password, there are another "
  1.6708 +"few possible problems to check."
  1.6709 +msgstr ""
  1.6710 +
  1.6711 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6712 +#: ../en/ch06-collab.xml:745
  1.6713 +msgid ""
  1.6714 +"Either the user's home directory or their <filename role=\"special\" class="
  1.6715 +"\"directory\">.ssh</filename> directory might have excessively liberal "
  1.6716 +"permissions.  As a result, the ssh daemon will not trust or read their "
  1.6717 +"<filename role=\"special\">authorized_keys</filename> file.  For example, a "
  1.6718 +"group-writable home or <filename role=\"special\" class=\"directory\">.ssh</"
  1.6719 +"filename> directory will often cause this symptom."
  1.6720 +msgstr ""
  1.6721 +
  1.6722 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6723 +#: ../en/ch06-collab.xml:754
  1.6724 +msgid ""
  1.6725 +"The user's <filename role=\"special\">authorized_keys</filename> file may "
  1.6726 +"have a problem. If anyone other than the user owns or can write to that file, "
  1.6727 +"the ssh daemon will not trust or read it."
  1.6728 +msgstr ""
  1.6729 +
  1.6730 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6731 +#: ../en/ch06-collab.xml:761
  1.6732 +msgid ""
  1.6733 +"In the ideal world, you should be able to run the following command "
  1.6734 +"successfully, and it should print exactly one line of output, the current "
  1.6735 +"date and time."
  1.6736 +msgstr ""
  1.6737 +
  1.6738 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6739 +#: ../en/ch06-collab.xml:766
  1.6740 +msgid ""
  1.6741 +"If, on your server, you have login scripts that print banners or other junk "
  1.6742 +"even when running non-interactive commands like this, you should fix them "
  1.6743 +"before you continue, so that they only print output if they're run "
  1.6744 +"interactively.  Otherwise these banners will at least clutter up Mercurial's "
  1.6745 +"output.  Worse, they could potentially cause problems with running Mercurial "
  1.6746 +"commands remotely.  Mercurial makes tries to detect and ignore banners in non-"
  1.6747 +"interactive <command>ssh</command> sessions, but it is not foolproof.  (If "
  1.6748 +"you're editing your login scripts on your server, the usual way to see if a "
  1.6749 +"login script is running in an interactive shell is to check the return code "
  1.6750 +"from the command <literal>tty -s</literal>.)"
  1.6751 +msgstr ""
  1.6752 +
  1.6753 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6754 +#: ../en/ch06-collab.xml:780
  1.6755 +msgid ""
  1.6756 +"Once you've verified that plain old ssh is working with your server, the next "
  1.6757 +"step is to ensure that Mercurial runs on the server.  The following command "
  1.6758 +"should run successfully:"
  1.6759 +msgstr ""
  1.6760 +
  1.6761 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6762 +#: ../en/ch06-collab.xml:785
  1.6763 +msgid ""
  1.6764 +"If you see an error message instead of normal <command role=\"hg-cmd\">hg "
  1.6765 +"version</command> output, this is usually because you haven't installed "
  1.6766 +"Mercurial to <filename class=\"directory\">/usr/bin</filename>.  Don't worry "
  1.6767 +"if this is the case; you don't need to do that.  But you should check for a "
  1.6768 +"few possible problems."
  1.6769 +msgstr ""
  1.6770 +
  1.6771 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6772 +#: ../en/ch06-collab.xml:792
  1.6773 +msgid ""
  1.6774 +"Is Mercurial really installed on the server at all? I know this sounds "
  1.6775 +"trivial, but it's worth checking!"
  1.6776 +msgstr ""
  1.6777 +
  1.6778 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6779 +#: ../en/ch06-collab.xml:796
  1.6780 +msgid ""
  1.6781 +"Maybe your shell's search path (usually set via the <envar>PATH</envar> "
  1.6782 +"environment variable) is simply misconfigured."
  1.6783 +msgstr ""
  1.6784 +
  1.6785 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6786 +#: ../en/ch06-collab.xml:800
  1.6787 +msgid ""
  1.6788 +"Perhaps your <envar>PATH</envar> environment variable is only being set to "
  1.6789 +"point to the location of the <command>hg</command> executable if the login "
  1.6790 +"session is interactive.  This can happen if you're setting the path in the "
  1.6791 +"wrong shell login script.  See your shell's documentation for details."
  1.6792 +msgstr ""
  1.6793 +
  1.6794 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.6795 +#: ../en/ch06-collab.xml:807
  1.6796 +msgid ""
  1.6797 +"The <envar>PYTHONPATH</envar> environment variable may need to contain the "
  1.6798 +"path to the Mercurial Python modules.  It might not be set at all; it could "
  1.6799 +"be incorrect; or it may be set only if the login is interactive."
  1.6800 +msgstr ""
  1.6801 +
  1.6802 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6803 +#: ../en/ch06-collab.xml:814
  1.6804 +msgid ""
  1.6805 +"If you can run <command role=\"hg-cmd\">hg version</command> over an ssh "
  1.6806 +"connection, well done! You've got the server and client sorted out.  You "
  1.6807 +"should now be able to use Mercurial to access repositories hosted by that "
  1.6808 +"username on that server.  If you run into problems with Mercurial and ssh at "
  1.6809 +"this point, try using the <option role=\"hg-opt-global\">--debug</option> "
  1.6810 +"option to get a clearer picture of what's going on."
  1.6811 +msgstr ""
  1.6812 +
  1.6813 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6814 +#: ../en/ch06-collab.xml:824
  1.6815 +msgid "Using compression with ssh"
  1.6816 +msgstr ""
  1.6817 +
  1.6818 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6819 +#: ../en/ch06-collab.xml:826
  1.6820 +msgid ""
  1.6821 +"Mercurial does not compress data when it uses the ssh protocol, because the "
  1.6822 +"ssh protocol can transparently compress data.  However, the default behaviour "
  1.6823 +"of ssh clients is <emphasis>not</emphasis> to request compression."
  1.6824 +msgstr ""
  1.6825 +
  1.6826 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6827 +#: ../en/ch06-collab.xml:831
  1.6828 +msgid ""
  1.6829 +"Over any network other than a fast LAN (even a wireless network), using "
  1.6830 +"compression is likely to significantly speed up Mercurial's network "
  1.6831 +"operations.  For example, over a WAN, someone measured compression as "
  1.6832 +"reducing the amount of time required to clone a particularly large repository "
  1.6833 +"from 51 minutes to 17 minutes."
  1.6834 +msgstr ""
  1.6835 +
  1.6836 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6837 +#: ../en/ch06-collab.xml:838
  1.6838 +msgid ""
  1.6839 +"Both <command>ssh</command> and <command>plink</command> accept a <option "
  1.6840 +"role=\"cmd-opt-ssh\">-C</option> option which turns on compression.  You can "
  1.6841 +"easily edit your <filename role=\"special\"> /.hgrc</filename>\\ to enable "
  1.6842 +"compression for all of Mercurial's uses of the ssh protocol."
  1.6843 +msgstr ""
  1.6844 +
  1.6845 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6846 +#: ../en/ch06-collab.xml:845
  1.6847 +msgid ""
  1.6848 +"If you use <command>ssh</command>, you can configure it to always use "
  1.6849 +"compression when talking to your server.  To do this, edit your <filename "
  1.6850 +"role=\"special\">.ssh/config</filename> file (which may not yet exist), as "
  1.6851 +"follows."
  1.6852 +msgstr ""
  1.6853 +
  1.6854 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6855 +#: ../en/ch06-collab.xml:852
  1.6856 +msgid ""
  1.6857 +"This defines an alias, <literal>hg</literal>.  When you use it on the "
  1.6858 +"<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-"
  1.6859 +"protocol URL, it will cause <command>ssh</command> to connect to <literal>hg."
  1.6860 +"example.com</literal> and use compression.  This gives you both a shorter "
  1.6861 +"name to type and compression, each of which is a good thing in its own right."
  1.6862 +msgstr ""
  1.6863 +
  1.6864 +#. type: Content of: <book><chapter><sect1><title>
  1.6865 +#: ../en/ch06-collab.xml:863
  1.6866 +msgid "Serving over HTTP using CGI"
  1.6867 +msgstr ""
  1.6868 +
  1.6869 +#. type: Content of: <book><chapter><sect1><para>
  1.6870 +#: ../en/ch06-collab.xml:865
  1.6871 +msgid ""
  1.6872 +"Depending on how ambitious you are, configuring Mercurial's CGI interface can "
  1.6873 +"take anything from a few moments to several hours."
  1.6874 +msgstr ""
  1.6875 +
  1.6876 +#. type: Content of: <book><chapter><sect1><para>
  1.6877 +#: ../en/ch06-collab.xml:869
  1.6878 +msgid ""
  1.6879 +"We'll begin with the simplest of examples, and work our way towards a more "
  1.6880 +"complex configuration.  Even for the most basic case, you're almost certainly "
  1.6881 +"going to need to read and modify your web server's configuration."
  1.6882 +msgstr ""
  1.6883 +
  1.6884 +#. type: Content of: <book><chapter><sect1><note><para>
  1.6885 +#: ../en/ch06-collab.xml:875
  1.6886 +msgid ""
  1.6887 +"Configuring a web server is a complex, fiddly, and highly system-dependent "
  1.6888 +"activity.  I can't possibly give you instructions that will cover anything "
  1.6889 +"like all of the cases you will encounter. Please use your discretion and "
  1.6890 +"judgment in following the sections below.  Be prepared to make plenty of "
  1.6891 +"mistakes, and to spend a lot of time reading your server's error logs."
  1.6892 +msgstr ""
  1.6893 +
  1.6894 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6895 +#: ../en/ch06-collab.xml:885
  1.6896 +msgid "Web server configuration checklist"
  1.6897 +msgstr ""
  1.6898 +
  1.6899 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6900 +#: ../en/ch06-collab.xml:887
  1.6901 +msgid ""
  1.6902 +"Before you continue, do take a few moments to check a few aspects of your "
  1.6903 +"system's setup."
  1.6904 +msgstr ""
  1.6905 +
  1.6906 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6907 +#: ../en/ch06-collab.xml:891
  1.6908 +msgid ""
  1.6909 +"Do you have a web server installed at all? Mac OS X ships with Apache, but "
  1.6910 +"many other systems may not have a web server installed."
  1.6911 +msgstr ""
  1.6912 +
  1.6913 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6914 +#: ../en/ch06-collab.xml:895
  1.6915 +msgid ""
  1.6916 +"If you have a web server installed, is it actually running? On most systems, "
  1.6917 +"even if one is present, it will be disabled by default."
  1.6918 +msgstr ""
  1.6919 +
  1.6920 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.6921 +#: ../en/ch06-collab.xml:899
  1.6922 +msgid ""
  1.6923 +"Is your server configured to allow you to run CGI programs in the directory "
  1.6924 +"where you plan to do so? Most servers default to explicitly disabling the "
  1.6925 +"ability to run CGI programs."
  1.6926 +msgstr ""
  1.6927 +
  1.6928 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6929 +#: ../en/ch06-collab.xml:905
  1.6930 +msgid ""
  1.6931 +"If you don't have a web server installed, and don't have substantial "
  1.6932 +"experience configuring Apache, you should consider using the "
  1.6933 +"<literal>lighttpd</literal> web server instead of Apache.  Apache has a well-"
  1.6934 +"deserved reputation for baroque and confusing configuration. While "
  1.6935 +"<literal>lighttpd</literal> is less capable in some ways than Apache, most of "
  1.6936 +"these capabilities are not relevant to serving Mercurial repositories.  And "
  1.6937 +"<literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier to "
  1.6938 +"get started with than Apache."
  1.6939 +msgstr ""
  1.6940 +
  1.6941 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.6942 +#: ../en/ch06-collab.xml:918
  1.6943 +msgid "Basic CGI configuration"
  1.6944 +msgstr ""
  1.6945 +
  1.6946 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6947 +#: ../en/ch06-collab.xml:920
  1.6948 +msgid ""
  1.6949 +"On Unix-like systems, it's common for users to have a subdirectory named "
  1.6950 +"something like <filename class=\"directory\">public_html</filename> in their "
  1.6951 +"home directory, from which they can serve up web pages.  A file named "
  1.6952 +"<filename>foo</filename> in this directory will be accessible at a URL of the "
  1.6953 +"form <literal>http://www.example.com/\\ {</literal>username/foo}."
  1.6954 +msgstr ""
  1.6955 +
  1.6956 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6957 +#: ../en/ch06-collab.xml:929
  1.6958 +msgid ""
  1.6959 +"To get started, find the <filename role=\"special\">hgweb.cgi</filename> "
  1.6960 +"script that should be present in your Mercurial installation.  If you can't "
  1.6961 +"quickly find a local copy on your system, simply download one from the master "
  1.6962 +"Mercurial repository at <ulink url=\"http://www.selenic.com/repo/hg/raw-file/"
  1.6963 +"tip/hgweb.cgi\">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>."
  1.6964 +msgstr ""
  1.6965 +
  1.6966 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6967 +#: ../en/ch06-collab.xml:936 ../en/ch06-collab.xml:1109
  1.6968 +msgid ""
  1.6969 +"You'll need to copy this script into your <filename class=\"directory"
  1.6970 +"\">public_html</filename> directory, and ensure that it's executable."
  1.6971 +msgstr ""
  1.6972 +
  1.6973 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.6974 +#: ../en/ch06-collab.xml:941
  1.6975 +msgid ""
  1.6976 +"The <literal>755</literal> argument to <command>chmod</command> is a little "
  1.6977 +"more general than just making the script executable: it ensures that the "
  1.6978 +"script is executable by anyone, and that <quote>group</quote> and "
  1.6979 +"<quote>other</quote> write permissions are <emphasis>not</emphasis> set.  If "
  1.6980 +"you were to leave those write permissions enabled, Apache's <literal>suexec</"
  1.6981 +"literal> subsystem would likely refuse to execute the script.  In fact, "
  1.6982 +"<literal>suexec</literal> also insists that the <emphasis>directory</"
  1.6983 +"emphasis> in which the script resides must not be writable by others."
  1.6984 +msgstr ""
  1.6985 +
  1.6986 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.6987 +#: ../en/ch06-collab.xml:955
  1.6988 +msgid "What could <emphasis>possibly</emphasis> go wrong?"
  1.6989 +msgstr ""
  1.6990 +
  1.6991 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.6992 +#: ../en/ch06-collab.xml:958
  1.6993 +msgid ""
  1.6994 +"Once you've copied the CGI script into place, go into a web browser, and try "
  1.6995 +"to open the URL <ulink url=\"http://myhostname/ myuser/hgweb.cgi\">http://"
  1.6996 +"myhostname/ myuser/hgweb.cgi</ulink>, <emphasis>but</emphasis> brace yourself "
  1.6997 +"for instant failure.  There's a high probability that trying to visit this "
  1.6998 +"URL will fail, and there are many possible reasons for this.  In fact, you're "
  1.6999 +"likely to stumble over almost every one of the possible errors below, so "
  1.7000 +"please read carefully.  The following are all of the problems I ran into on a "
  1.7001 +"system running Fedora 7, with a fresh installation of Apache, and a user "
  1.7002 +"account that I created specially to perform this exercise."
  1.7003 +msgstr ""
  1.7004 +
  1.7005 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7006 +#: ../en/ch06-collab.xml:972
  1.7007 +msgid ""
  1.7008 +"Your web server may have per-user directories disabled.  If you're using "
  1.7009 +"Apache, search your config file for a <literal>UserDir</literal> directive.  "
  1.7010 +"If there's none present, per-user directories will be disabled.  If one "
  1.7011 +"exists, but its value is <literal>disabled</literal>, then per-user "
  1.7012 +"directories will be disabled.  Otherwise, the string after <literal>UserDir</"
  1.7013 +"literal> gives the name of the subdirectory that Apache will look in under "
  1.7014 +"your home directory, for example <filename class=\"directory\">public_html</"
  1.7015 +"filename>."
  1.7016 +msgstr ""
  1.7017 +
  1.7018 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7019 +#: ../en/ch06-collab.xml:983
  1.7020 +msgid ""
  1.7021 +"Your file access permissions may be too restrictive.  The web server must be "
  1.7022 +"able to traverse your home directory and directories under your <filename "
  1.7023 +"class=\"directory\">public_html</filename> directory, and read files under "
  1.7024 +"the latter too.  Here's a quick recipe to help you to make your permissions "
  1.7025 +"more appropriate."
  1.7026 +msgstr ""
  1.7027 +
  1.7028 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7029 +#: ../en/ch06-collab.xml:993
  1.7030 +msgid ""
  1.7031 +"The other possibility with permissions is that you might get a completely "
  1.7032 +"empty window when you try to load the script.  In this case, it's likely that "
  1.7033 +"your access permissions are <emphasis>too permissive</emphasis>.  Apache's "
  1.7034 +"<literal>suexec</literal> subsystem won't execute a script that's group- or "
  1.7035 +"world-writable, for example."
  1.7036 +msgstr ""
  1.7037 +
  1.7038 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7039 +#: ../en/ch06-collab.xml:1000
  1.7040 +msgid ""
  1.7041 +"Your web server may be configured to disallow execution of CGI programs in "
  1.7042 +"your per-user web directory.  Here's Apache's default per-user configuration "
  1.7043 +"from my Fedora system."
  1.7044 +msgstr ""
  1.7045 +
  1.7046 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7047 +#: ../en/ch06-collab.xml:1011
  1.7048 +msgid ""
  1.7049 +"If you find a similar-looking <literal>Directory</literal> group in your "
  1.7050 +"Apache configuration, the directive to look at inside it is <literal>Options</"
  1.7051 +"literal>. Add <literal>ExecCGI</literal> to the end of this list if it's "
  1.7052 +"missing, and restart the web server."
  1.7053 +msgstr ""
  1.7054 +
  1.7055 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7056 +#: ../en/ch06-collab.xml:1018
  1.7057 +msgid ""
  1.7058 +"If you find that Apache serves you the text of the CGI script instead of "
  1.7059 +"executing it, you may need to either uncomment (if already present) or add a "
  1.7060 +"directive like this."
  1.7061 +msgstr ""
  1.7062 +
  1.7063 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7064 +#: ../en/ch06-collab.xml:1024
  1.7065 +msgid ""
  1.7066 +"The next possibility is that you might be served with a colourful Python "
  1.7067 +"backtrace claiming that it can't import a <literal>mercurial</literal>-"
  1.7068 +"related module.  This is actually progress! The server is now capable of "
  1.7069 +"executing your CGI script.  This error is only likely to occur if you're "
  1.7070 +"running a private installation of Mercurial, instead of a system-wide "
  1.7071 +"version.  Remember that the web server runs the CGI program without any of "
  1.7072 +"the environment variables that you take for granted in an interactive "
  1.7073 +"session.  If this error happens to you, edit your copy of <filename role="
  1.7074 +"\"special\">hgweb.cgi</filename> and follow the directions inside it to "
  1.7075 +"correctly set your <envar>PYTHONPATH</envar> environment variable."
  1.7076 +msgstr ""
  1.7077 +
  1.7078 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7079 +#: ../en/ch06-collab.xml:1038
  1.7080 +msgid ""
  1.7081 +"Finally, you are <emphasis>certain</emphasis> to by served with another "
  1.7082 +"colourful Python backtrace: this one will complain that it can't find "
  1.7083 +"<filename class=\"directory\">/path/to/repository</filename>.  Edit your "
  1.7084 +"<filename role=\"special\">hgweb.cgi</filename> script and replace the "
  1.7085 +"<filename class=\"directory\">/path/to/repository</filename> string with the "
  1.7086 +"complete path to the repository you want to serve up."
  1.7087 +msgstr ""
  1.7088 +
  1.7089 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7090 +#: ../en/ch06-collab.xml:1048
  1.7091 +msgid ""
  1.7092 +"At this point, when you try to reload the page, you should be presented with "
  1.7093 +"a nice HTML view of your repository's history.  Whew!"
  1.7094 +msgstr ""
  1.7095 +
  1.7096 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.7097 +#: ../en/ch06-collab.xml:1054
  1.7098 +msgid "Configuring lighttpd"
  1.7099 +msgstr ""
  1.7100 +
  1.7101 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7102 +#: ../en/ch06-collab.xml:1056
  1.7103 +msgid ""
  1.7104 +"To be exhaustive in my experiments, I tried configuring the increasingly "
  1.7105 +"popular <literal>lighttpd</literal> web server to serve the same repository "
  1.7106 +"as I described with Apache above.  I had already overcome all of the problems "
  1.7107 +"I outlined with Apache, many of which are not server-specific.  As a result, "
  1.7108 +"I was fairly sure that my file and directory permissions were good, and that "
  1.7109 +"my <filename role=\"special\">hgweb.cgi</filename> script was properly edited."
  1.7110 +msgstr ""
  1.7111 +
  1.7112 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7113 +#: ../en/ch06-collab.xml:1066
  1.7114 +msgid ""
  1.7115 +"Once I had Apache running, getting <literal>lighttpd</literal> to serve the "
  1.7116 +"repository was a snap (in other words, even if you're trying to use "
  1.7117 +"<literal>lighttpd</literal>, you should read the Apache section).  I first "
  1.7118 +"had to edit the <literal>mod_access</literal> section of its config file to "
  1.7119 +"enable <literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of "
  1.7120 +"which were disabled by default on my system.  I then added a few lines to the "
  1.7121 +"end of the config file, to configure these modules."
  1.7122 +msgstr ""
  1.7123 +
  1.7124 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7125 +#: ../en/ch06-collab.xml:1078
  1.7126 +msgid ""
  1.7127 +"With this done, <literal>lighttpd</literal> ran immediately for me.  If I had "
  1.7128 +"configured <literal>lighttpd</literal> before Apache, I'd almost certainly "
  1.7129 +"have run into many of the same system-level configuration problems as I did "
  1.7130 +"with Apache.  However, I found <literal>lighttpd</literal> to be noticeably "
  1.7131 +"easier to configure than Apache, even though I've used Apache for over a "
  1.7132 +"decade, and this was my first exposure to <literal>lighttpd</literal>."
  1.7133 +msgstr ""
  1.7134 +
  1.7135 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.7136 +#: ../en/ch06-collab.xml:1091
  1.7137 +msgid "Sharing multiple repositories with one CGI script"
  1.7138 +msgstr ""
  1.7139 +
  1.7140 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7141 +#: ../en/ch06-collab.xml:1093
  1.7142 +msgid ""
  1.7143 +"The <filename role=\"special\">hgweb.cgi</filename> script only lets you "
  1.7144 +"publish a single repository, which is an annoying restriction.  If you want "
  1.7145 +"to publish more than one without wracking yourself with multiple copies of "
  1.7146 +"the same script, each with different names, a better choice is to use the "
  1.7147 +"<filename role=\"special\">hgwebdir.cgi</filename> script."
  1.7148 +msgstr ""
  1.7149 +
  1.7150 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7151 +#: ../en/ch06-collab.xml:1101
  1.7152 +msgid ""
  1.7153 +"The procedure to configure <filename role=\"special\">hgwebdir.cgi</filename> "
  1.7154 +"is only a little more involved than for <filename role=\"special\">hgweb.cgi</"
  1.7155 +"filename>.  First, you must obtain a copy of the script.  If you don't have "
  1.7156 +"one handy, you can download a copy from the master Mercurial repository at "
  1.7157 +"<ulink url=\"http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi"
  1.7158 +"\">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>."
  1.7159 +msgstr ""
  1.7160 +
  1.7161 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7162 +#: ../en/ch06-collab.xml:1114
  1.7163 +msgid ""
  1.7164 +"With basic configuration out of the way, try to visit <ulink url=\"http://"
  1.7165 +"myhostname/ myuser/hgwebdir.cgi\">http://myhostname/ myuser/hgwebdir.cgi</"
  1.7166 +"ulink> in your browser.  It should display an empty list of repositories.  If "
  1.7167 +"you get a blank window or error message, try walking through the list of "
  1.7168 +"potential problems in section <xref linkend=\"sec.collab.wtf\"/>."
  1.7169 +msgstr ""
  1.7170 +
  1.7171 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7172 +#: ../en/ch06-collab.xml:1123
  1.7173 +msgid ""
  1.7174 +"The <filename role=\"special\">hgwebdir.cgi</filename> script relies on an "
  1.7175 +"external configuration file.  By default, it searches for a file named "
  1.7176 +"<filename role=\"special\">hgweb.config</filename> in the same directory as "
  1.7177 +"itself.  You'll need to create this file, and make it world-readable.  The "
  1.7178 +"format of the file is similar to a Windows <quote>ini</quote> file, as "
  1.7179 +"understood by Python's <literal>ConfigParser</literal> <citation>web:"
  1.7180 +"configparser</citation> module."
  1.7181 +msgstr ""
  1.7182 +
  1.7183 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7184 +#: ../en/ch06-collab.xml:1133
  1.7185 +msgid ""
  1.7186 +"The easiest way to configure <filename role=\"special\">hgwebdir.cgi</"
  1.7187 +"filename> is with a section named <literal>collections</literal>.  This will "
  1.7188 +"automatically publish <emphasis>every</emphasis> repository under the "
  1.7189 +"directories you name.  The section should look like this:"
  1.7190 +msgstr ""
  1.7191 +
  1.7192 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7193 +#: ../en/ch06-collab.xml:1141
  1.7194 +msgid ""
  1.7195 +"Mercurial interprets this by looking at the directory name on the "
  1.7196 +"<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></"
  1.7197 +"quote> sign; finding repositories in that directory hierarchy; and using the "
  1.7198 +"text on the <emphasis>left</emphasis> to strip off matching text from the "
  1.7199 +"names it will actually list in the web interface.  The remaining component of "
  1.7200 +"a path after this stripping has occurred is called a <quote>virtual path</"
  1.7201 +"quote>."
  1.7202 +msgstr ""
  1.7203 +
  1.7204 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7205 +#: ../en/ch06-collab.xml:1150
  1.7206 +msgid ""
  1.7207 +"Given the example above, if we have a repository whose local path is "
  1.7208 +"<filename class=\"directory\">/my/root/this/repo</filename>, the CGI script "
  1.7209 +"will strip the leading <filename class=\"directory\">/my/root</filename> from "
  1.7210 +"the name, and publish the repository with a virtual path of <filename class="
  1.7211 +"\"directory\">this/repo</filename>.  If the base URL for our CGI script is "
  1.7212 +"<ulink url=\"http://myhostname/ myuser/hgwebdir.cgi\">http://myhostname/ "
  1.7213 +"myuser/hgwebdir.cgi</ulink>, the complete URL for that repository will be "
  1.7214 +"<ulink url=\"http://myhostname/ myuser/hgwebdir.cgi/this/repo\">http://"
  1.7215 +"myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>."
  1.7216 +msgstr ""
  1.7217 +
  1.7218 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7219 +#: ../en/ch06-collab.xml:1164
  1.7220 +msgid ""
  1.7221 +"If we replace <filename class=\"directory\">/my/root</filename> on the left "
  1.7222 +"hand side of this example with <filename class=\"directory\">/my</filename>, "
  1.7223 +"then <filename role=\"special\">hgwebdir.cgi</filename> will only strip off "
  1.7224 +"<filename class=\"directory\">/my</filename> from the repository name, and "
  1.7225 +"will give us a virtual path of <filename class=\"directory\">root/this/repo</"
  1.7226 +"filename> instead of <filename class=\"directory\">this/repo</filename>."
  1.7227 +msgstr ""
  1.7228 +
  1.7229 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7230 +#: ../en/ch06-collab.xml:1174
  1.7231 +msgid ""
  1.7232 +"The <filename role=\"special\">hgwebdir.cgi</filename> script will "
  1.7233 +"recursively search each directory listed in the <literal>collections</"
  1.7234 +"literal> section of its configuration file, but it will <literal>not</"
  1.7235 +"literal> recurse into the repositories it finds."
  1.7236 +msgstr ""
  1.7237 +
  1.7238 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7239 +#: ../en/ch06-collab.xml:1180
  1.7240 +msgid ""
  1.7241 +"The <literal>collections</literal> mechanism makes it easy to publish many "
  1.7242 +"repositories in a <quote>fire and forget</quote> manner.  You only need to "
  1.7243 +"set up the CGI script and configuration file one time.  Afterwards, you can "
  1.7244 +"publish or unpublish a repository at any time by simply moving it into, or "
  1.7245 +"out of, the directory hierarchy in which you've configured <filename role="
  1.7246 +"\"special\">hgwebdir.cgi</filename> to look."
  1.7247 +msgstr ""
  1.7248 +
  1.7249 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.7250 +#: ../en/ch06-collab.xml:1190
  1.7251 +msgid "Explicitly specifying which repositories to publish"
  1.7252 +msgstr ""
  1.7253 +
  1.7254 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7255 +#: ../en/ch06-collab.xml:1193
  1.7256 +msgid ""
  1.7257 +"In addition to the <literal>collections</literal> mechanism, the <filename "
  1.7258 +"role=\"special\">hgwebdir.cgi</filename> script allows you to publish a "
  1.7259 +"specific list of repositories.  To do so, create a <literal>paths</literal> "
  1.7260 +"section, with contents of the following form."
  1.7261 +msgstr ""
  1.7262 +
  1.7263 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7264 +#: ../en/ch06-collab.xml:1201
  1.7265 +msgid ""
  1.7266 +"In this case, the virtual path (the component that will appear in a URL) is "
  1.7267 +"on the left hand side of each definition, while the path to the repository is "
  1.7268 +"on the right.  Notice that there does not need to be any relationship between "
  1.7269 +"the virtual path you choose and the location of a repository in your "
  1.7270 +"filesystem."
  1.7271 +msgstr ""
  1.7272 +
  1.7273 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7274 +#: ../en/ch06-collab.xml:1208
  1.7275 +msgid ""
  1.7276 +"If you wish, you can use both the <literal>collections</literal> and "
  1.7277 +"<literal>paths</literal> mechanisms simultaneously in a single configuration "
  1.7278 +"file."
  1.7279 +msgstr ""
  1.7280 +
  1.7281 +#. type: Content of: <book><chapter><sect1><sect2><sect3><note><para>
  1.7282 +#: ../en/ch06-collab.xml:1214
  1.7283 +msgid ""
  1.7284 +"If multiple repositories have the same virtual path, <filename role=\"special"
  1.7285 +"\">hgwebdir.cgi</filename> will not report an error.  Instead, it will behave "
  1.7286 +"unpredictably."
  1.7287 +msgstr ""
  1.7288 +
  1.7289 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.7290 +#: ../en/ch06-collab.xml:1223
  1.7291 +msgid "Downloading source archives"
  1.7292 +msgstr ""
  1.7293 +
  1.7294 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7295 +#: ../en/ch06-collab.xml:1225
  1.7296 +msgid ""
  1.7297 +"Mercurial's web interface lets users download an archive of any revision.  "
  1.7298 +"This archive will contain a snapshot of the working directory as of that "
  1.7299 +"revision, but it will not contain a copy of the repository data."
  1.7300 +msgstr ""
  1.7301 +
  1.7302 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7303 +#: ../en/ch06-collab.xml:1230
  1.7304 +msgid ""
  1.7305 +"By default, this feature is not enabled.  To enable it, you'll need to add an "
  1.7306 +"<envar role=\"rc-item-web\">allow_archive</envar> item to the <literal role="
  1.7307 +"\"rc-web\">web</literal> section of your <filename role=\"special\"> /.hgrc</"
  1.7308 +"filename>."
  1.7309 +msgstr ""
  1.7310 +
  1.7311 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.7312 +#: ../en/ch06-collab.xml:1238
  1.7313 +msgid "Web configuration options"
  1.7314 +msgstr ""
  1.7315 +
  1.7316 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7317 +#: ../en/ch06-collab.xml:1240
  1.7318 +msgid ""
  1.7319 +"Mercurial's web interfaces (the <command role=\"hg-cmd\">hg serve</command> "
  1.7320 +"command, and the <filename role=\"special\">hgweb.cgi</filename> and "
  1.7321 +"<filename role=\"special\">hgwebdir.cgi</filename> scripts) have a number of "
  1.7322 +"configuration options that you can set.  These belong in a section named "
  1.7323 +"<literal role=\"rc-web\">web</literal>."
  1.7324 +msgstr ""
  1.7325 +
  1.7326 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7327 +#: ../en/ch06-collab.xml:1248
  1.7328 +msgid ""
  1.7329 +"<envar role=\"rc-item-web\">allow_archive</envar>: Determines which (if any) "
  1.7330 +"archive download mechanisms Mercurial supports.  If you enable this feature, "
  1.7331 +"users of the web interface will be able to download an archive of whatever "
  1.7332 +"revision of a repository they are viewing. To enable the archive feature, "
  1.7333 +"this item must take the form of a sequence of words drawn from the list below."
  1.7334 +msgstr ""
  1.7335 +
  1.7336 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para>
  1.7337 +#: ../en/ch06-collab.xml:1257
  1.7338 +msgid ""
  1.7339 +"<literal>bz2</literal>: A <command>tar</command> archive, compressed using "
  1.7340 +"<literal>bzip2</literal> compression.  This has the best compression ratio, "
  1.7341 +"but uses the most CPU time on the server."
  1.7342 +msgstr ""
  1.7343 +
  1.7344 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para>
  1.7345 +#: ../en/ch06-collab.xml:1263
  1.7346 +msgid ""
  1.7347 +"<literal>gz</literal>: A <command>tar</command> archive, compressed using "
  1.7348 +"<literal>gzip</literal> compression."
  1.7349 +msgstr ""
  1.7350 +
  1.7351 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><itemizedlist><listitem><para>
  1.7352 +#: ../en/ch06-collab.xml:1267
  1.7353 +msgid ""
  1.7354 +"<literal>zip</literal>: A <command>zip</command> archive, compressed using "
  1.7355 +"LZW compression.  This format has the worst compression ratio, but is widely "
  1.7356 +"used in the Windows world."
  1.7357 +msgstr ""
  1.7358 +
  1.7359 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7360 +#: ../en/ch06-collab.xml:1273
  1.7361 +msgid ""
  1.7362 +"If you provide an empty list, or don't have an <envar role=\"rc-item-web"
  1.7363 +"\">allow_archive</envar> entry at all, this feature will be disabled.  Here "
  1.7364 +"is an example of how to enable all three supported formats."
  1.7365 +msgstr ""
  1.7366 +
  1.7367 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7368 +#: ../en/ch06-collab.xml:1280
  1.7369 +msgid ""
  1.7370 +"<envar role=\"rc-item-web\">allowpull</envar>: Boolean.  Determines whether "
  1.7371 +"the web interface allows remote users to <command role=\"hg-cmd\">hg pull</"
  1.7372 +"command> and <command role=\"hg-cmd\">hg clone</command> this repository over "
  1.7373 +"HTTP.  If set to <literal>no</literal> or <literal>false</literal>, only the "
  1.7374 +"<quote>human-oriented</quote> portion of the web interface is available."
  1.7375 +msgstr ""
  1.7376 +
  1.7377 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7378 +#: ../en/ch06-collab.xml:1289
  1.7379 +msgid ""
  1.7380 +"<envar role=\"rc-item-web\">contact</envar>: String.  A free-form (but "
  1.7381 +"preferably brief) string identifying the person or group in charge of the "
  1.7382 +"repository.  This often contains the name and email address of a person or "
  1.7383 +"mailing list.  It often makes sense to place this entry in a repository's own "
  1.7384 +"<filename role=\"special\">.hg/hgrc</filename> file, but it can make sense to "
  1.7385 +"use in a global <filename role=\"special\"> /.hgrc</filename>\\ if every "
  1.7386 +"repository has a single maintainer."
  1.7387 +msgstr ""
  1.7388 +
  1.7389 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7390 +#: ../en/ch06-collab.xml:1300
  1.7391 +msgid ""
  1.7392 +"<envar role=\"rc-item-web\">maxchanges</envar>: Integer.  The default maximum "
  1.7393 +"number of changesets to display in a single page of output."
  1.7394 +msgstr ""
  1.7395 +
  1.7396 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7397 +#: ../en/ch06-collab.xml:1304
  1.7398 +msgid ""
  1.7399 +"<envar role=\"rc-item-web\">maxfiles</envar>: Integer.  The default maximum "
  1.7400 +"number of modified files to display in a single page of output."
  1.7401 +msgstr ""
  1.7402 +
  1.7403 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7404 +#: ../en/ch06-collab.xml:1308
  1.7405 +msgid ""
  1.7406 +"<envar role=\"rc-item-web\">stripes</envar>: Integer.  If the web interface "
  1.7407 +"displays alternating <quote>stripes</quote> to make it easier to visually "
  1.7408 +"align rows when you are looking at a table, this number controls the number "
  1.7409 +"of rows in each stripe."
  1.7410 +msgstr ""
  1.7411 +
  1.7412 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7413 +#: ../en/ch06-collab.xml:1314
  1.7414 +msgid ""
  1.7415 +"<envar role=\"rc-item-web\">style</envar>: Controls the template Mercurial "
  1.7416 +"uses to display the web interface.  Mercurial ships with two web templates, "
  1.7417 +"named <literal>default</literal> and <literal>gitweb</literal> (the latter is "
  1.7418 +"much more visually attractive).  You can also specify a custom template of "
  1.7419 +"your own; see chapter <xref linkend=\"chap.template\"/> for details.  Here, "
  1.7420 +"you can see how to enable the <literal>gitweb</literal> style."
  1.7421 +msgstr ""
  1.7422 +
  1.7423 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.7424 +#: ../en/ch06-collab.xml:1325
  1.7425 +msgid ""
  1.7426 +"<envar role=\"rc-item-web\">templates</envar>: Path.  The directory in which "
  1.7427 +"to search for template files.  By default, Mercurial searches in the "
  1.7428 +"directory in which it was installed."
  1.7429 +msgstr ""
  1.7430 +
  1.7431 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7432 +#: ../en/ch06-collab.xml:1330
  1.7433 +msgid ""
  1.7434 +"If you are using <filename role=\"special\">hgwebdir.cgi</filename>, you can "
  1.7435 +"place a few configuration items in a <literal role=\"rc-web\">web</literal> "
  1.7436 +"section of the <filename role=\"special\">hgweb.config</filename> file "
  1.7437 +"instead of a <filename role=\"special\"> /.hgrc</filename>\\ file, for "
  1.7438 +"convenience.  These items are <envar role=\"rc-item-web\">motd</envar> and "
  1.7439 +"<envar role=\"rc-item-web\">style</envar>."
  1.7440 +msgstr ""
  1.7441 +
  1.7442 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.7443 +#: ../en/ch06-collab.xml:1341
  1.7444 +msgid "Options specific to an individual repository"
  1.7445 +msgstr ""
  1.7446 +
  1.7447 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7448 +#: ../en/ch06-collab.xml:1343
  1.7449 +msgid ""
  1.7450 +"A few <literal role=\"rc-web\">web</literal> configuration items ought to be "
  1.7451 +"placed in a repository's local <filename role=\"special\">.hg/hgrc</"
  1.7452 +"filename>, rather than a user's or global <filename role=\"special\"> /.hgrc</"
  1.7453 +"filename>."
  1.7454 +msgstr ""
  1.7455 +
  1.7456 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.7457 +#: ../en/ch06-collab.xml:1349
  1.7458 +msgid ""
  1.7459 +"<envar role=\"rc-item-web\">description</envar>: String.  A free-form (but "
  1.7460 +"preferably brief) string that describes the contents or purpose of the "
  1.7461 +"repository."
  1.7462 +msgstr ""
  1.7463 +
  1.7464 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.7465 +#: ../en/ch06-collab.xml:1354
  1.7466 +msgid ""
  1.7467 +"<envar role=\"rc-item-web\">name</envar>: String.  The name to use for the "
  1.7468 +"repository in the web interface.  This overrides the default name, which is "
  1.7469 +"the last component of the repository's path."
  1.7470 +msgstr ""
  1.7471 +
  1.7472 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.7473 +#: ../en/ch06-collab.xml:1362
  1.7474 +msgid ""
  1.7475 +"Options specific to the <command role=\"hg-cmd\">hg serve</command> command"
  1.7476 +msgstr ""
  1.7477 +
  1.7478 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7479 +#: ../en/ch06-collab.xml:1365
  1.7480 +msgid ""
  1.7481 +"Some of the items in the <literal role=\"rc-web\">web</literal> section of a "
  1.7482 +"<filename role=\"special\"> /.hgrc</filename>\\ file are only for use with "
  1.7483 +"the <command role=\"hg-cmd\">hg serve</command> command."
  1.7484 +msgstr ""
  1.7485 +
  1.7486 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.7487 +#: ../en/ch06-collab.xml:1371
  1.7488 +msgid ""
  1.7489 +"<envar role=\"rc-item-web\">accesslog</envar>: Path.  The name of a file into "
  1.7490 +"which to write an access log.  By default, the <command role=\"hg-cmd\">hg "
  1.7491 +"serve</command> command writes this information to standard output, not to a "
  1.7492 +"file.  Log entries are written in the standard <quote>combined</quote> file "
  1.7493 +"format used by almost all web servers."
  1.7494 +msgstr ""
  1.7495 +
  1.7496 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.7497 +#: ../en/ch06-collab.xml:1379
  1.7498 +msgid ""
  1.7499 +"<envar role=\"rc-item-web\">address</envar>: String.  The local address on "
  1.7500 +"which the server should listen for incoming connections.  By default, the "
  1.7501 +"server listens on all addresses."
  1.7502 +msgstr ""
  1.7503 +
  1.7504 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.7505 +#: ../en/ch06-collab.xml:1384
  1.7506 +msgid ""
  1.7507 +"<envar role=\"rc-item-web\">errorlog</envar>: Path.  The name of a file into "
  1.7508 +"which to write an error log.  By default, the <command role=\"hg-cmd\">hg "
  1.7509 +"serve</command> command writes this information to standard error, not to a "
  1.7510 +"file."
  1.7511 +msgstr ""
  1.7512 +
  1.7513 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.7514 +#: ../en/ch06-collab.xml:1390
  1.7515 +msgid ""
  1.7516 +"<envar role=\"rc-item-web\">ipv6</envar>: Boolean.  Whether to use the IPv6 "
  1.7517 +"protocol. By default, IPv6 is not used."
  1.7518 +msgstr ""
  1.7519 +
  1.7520 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
  1.7521 +#: ../en/ch06-collab.xml:1394
  1.7522 +msgid ""
  1.7523 +"<envar role=\"rc-item-web\">port</envar>: Integer.  The TCP port number on "
  1.7524 +"which the server should listen.  The default port number used is 8000."
  1.7525 +msgstr ""
  1.7526 +
  1.7527 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.7528 +#: ../en/ch06-collab.xml:1401
  1.7529 +msgid ""
  1.7530 +"Choosing the right <filename role=\"special\"> /.hgrc</filename>\\ file to "
  1.7531 +"add <literal role=\"rc-web\">web</literal> items to"
  1.7532 +msgstr ""
  1.7533 +
  1.7534 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7535 +#: ../en/ch06-collab.xml:1405
  1.7536 +msgid ""
  1.7537 +"It is important to remember that a web server like Apache or "
  1.7538 +"<literal>lighttpd</literal> will run under a user ID that is different to "
  1.7539 +"yours. CGI scripts run by your server, such as <filename role=\"special"
  1.7540 +"\">hgweb.cgi</filename>, will usually also run under that user ID."
  1.7541 +msgstr ""
  1.7542 +
  1.7543 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7544 +#: ../en/ch06-collab.xml:1412
  1.7545 +msgid ""
  1.7546 +"If you add <literal role=\"rc-web\">web</literal> items to your own personal "
  1.7547 +"<filename role=\"special\"> /.hgrc</filename>\\ file, CGI scripts won't read "
  1.7548 +"that <filename role=\"special\"> /.hgrc</filename>\\ file.  Those settings "
  1.7549 +"will thus only affect the behaviour of the <command role=\"hg-cmd\">hg serve</"
  1.7550 +"command> command when you run it.  To cause CGI scripts to see your settings, "
  1.7551 +"either create a <filename role=\"special\"> /.hgrc</filename>\\ file in the "
  1.7552 +"home directory of the user ID that runs your web server, or add those "
  1.7553 +"settings to a system-wide <filename role=\"special\"> /.hgrc</filename>\\ "
  1.7554 +"file."
  1.7555 +msgstr ""
  1.7556 +
  1.7557 +#. type: Content of: <book><chapter><title>
  1.7558 +#: ../en/ch07-filenames.xml:5
  1.7559 +msgid "File names and pattern matching"
  1.7560 +msgstr "文件名称与模式匹配"
  1.7561 +
  1.7562 +#. type: Content of: <book><chapter><para>
  1.7563 +#: ../en/ch07-filenames.xml:7
  1.7564 +msgid ""
  1.7565 +"Mercurial provides mechanisms that let you work with file names in a "
  1.7566 +"consistent and expressive way."
  1.7567 +msgstr ""
  1.7568 +
  1.7569 +#. type: Content of: <book><chapter><sect1><title>
  1.7570 +#: ../en/ch07-filenames.xml:11
  1.7571 +msgid "Simple file naming"
  1.7572 +msgstr ""
  1.7573 +
  1.7574 +#. type: Content of: <book><chapter><sect1><para>
  1.7575 +#: ../en/ch07-filenames.xml:13
  1.7576 +msgid ""
  1.7577 +"Mercurial uses a unified piece of machinery <quote>under the hood</quote> to "
  1.7578 +"handle file names.  Every command behaves uniformly with respect to file "
  1.7579 +"names.  The way in which commands work with file names is as follows."
  1.7580 +msgstr ""
  1.7581 +
  1.7582 +#. type: Content of: <book><chapter><sect1><para>
  1.7583 +#: ../en/ch07-filenames.xml:18
  1.7584 +msgid ""
  1.7585 +"If you explicitly name real files on the command line, Mercurial works with "
  1.7586 +"exactly those files, as you would expect.  &interaction.filenames.files;"
  1.7587 +msgstr ""
  1.7588 +
  1.7589 +#
  1.7590 +#. type: Content of: <book><chapter><sect1><para>
  1.7591 +#: ../en/ch07-filenames.xml:22
  1.7592 +msgid ""
  1.7593 +"When you provide a directory name, Mercurial will interpret this as "
  1.7594 +"<quote>operate on every file in this directory and its subdirectories</"
  1.7595 +"quote>. Mercurial traverses the files and subdirectories in a directory in "
  1.7596 +"alphabetical order.  When it encounters a subdirectory, it will traverse that "
  1.7597 +"subdirectory before continuing with the current directory."
  1.7598 +msgstr ""
  1.7599 +
  1.7600 +#. type: Content of: <book><chapter><sect1><title>
  1.7601 +#: ../en/ch07-filenames.xml:33
  1.7602 +msgid "Running commands without any file names"
  1.7603 +msgstr ""
  1.7604 +
  1.7605 +#. type: Content of: <book><chapter><sect1><para>
  1.7606 +#: ../en/ch07-filenames.xml:35
  1.7607 +msgid ""
  1.7608 +"Mercurial's commands that work with file names have useful default behaviours "
  1.7609 +"when you invoke them without providing any file names or patterns.  What kind "
  1.7610 +"of behaviour you should expect depends on what the command does.  Here are a "
  1.7611 +"few rules of thumb you can use to predict what a command is likely to do if "
  1.7612 +"you don't give it any names to work with."
  1.7613 +msgstr ""
  1.7614 +
  1.7615 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.7616 +#: ../en/ch07-filenames.xml:42
  1.7617 +msgid ""
  1.7618 +"Most commands will operate on the entire working directory. This is what the "
  1.7619 +"<command role=\"hg-cmd\">hg add</command> command does, for example."
  1.7620 +msgstr ""
  1.7621 +
  1.7622 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.7623 +#: ../en/ch07-filenames.xml:46
  1.7624 +msgid ""
  1.7625 +"If the command has effects that are difficult or impossible to reverse, it "
  1.7626 +"will force you to explicitly provide at least one name or pattern (see "
  1.7627 +"below).  This protects you from accidentally deleting files by running "
  1.7628 +"<command role=\"hg-cmd\">hg remove</command> with no arguments, for example."
  1.7629 +msgstr ""
  1.7630 +
  1.7631 +#
  1.7632 +#. type: Content of: <book><chapter><sect1><para>
  1.7633 +#: ../en/ch07-filenames.xml:54
  1.7634 +msgid ""
  1.7635 +"It's easy to work around these default behaviours if they don't suit you.  If "
  1.7636 +"a command normally operates on the whole working directory, you can invoke it "
  1.7637 +"on just the current directory and its subdirectories by giving it the name "
  1.7638 +"<quote><filename class=\"directory\">.</filename></quote>."
  1.7639 +msgstr ""
  1.7640 +
  1.7641 +#
  1.7642 +#. type: Content of: <book><chapter><sect1><para>
  1.7643 +#: ../en/ch07-filenames.xml:62
  1.7644 +msgid ""
  1.7645 +"Along the same lines, some commands normally print file names relative to the "
  1.7646 +"root of the repository, even if you're invoking them from a subdirectory.  "
  1.7647 +"Such a command will print file names relative to your subdirectory if you "
  1.7648 +"give it explicit names.  Here, we're going to run <command role=\"hg-cmd\">hg "
  1.7649 +"status</command> from a subdirectory, and get it to operate on the entire "
  1.7650 +"working directory while printing file names relative to our subdirectory, by "
  1.7651 +"passing it the output of the <command role=\"hg-cmd\">hg root</command> "
  1.7652 +"command."
  1.7653 +msgstr ""
  1.7654 +
  1.7655 +#. type: Content of: <book><chapter><sect1><title>
  1.7656 +#: ../en/ch07-filenames.xml:76
  1.7657 +msgid "Telling you what's going on"
  1.7658 +msgstr ""
  1.7659 +
  1.7660 +#. type: Content of: <book><chapter><sect1><para>
  1.7661 +#: ../en/ch07-filenames.xml:78
  1.7662 +msgid ""
  1.7663 +"The <command role=\"hg-cmd\">hg add</command> example in the preceding "
  1.7664 +"section illustrates something else that's helpful about Mercurial commands.  "
  1.7665 +"If a command operates on a file that you didn't name explicitly on the "
  1.7666 +"command line, it will usually print the name of the file, so that you will "
  1.7667 +"not be surprised what's going on."
  1.7668 +msgstr ""
  1.7669 +
  1.7670 +#. type: Content of: <book><chapter><sect1><para>
  1.7671 +#: ../en/ch07-filenames.xml:85
  1.7672 +msgid ""
  1.7673 +"The principle here is of <emphasis>least surprise</emphasis>.  If you've "
  1.7674 +"exactly named a file on the command line, there's no point in repeating it "
  1.7675 +"back at you.  If Mercurial is acting on a file <emphasis>implicitly</"
  1.7676 +"emphasis>, because you provided no names, or a directory, or a pattern (see "
  1.7677 +"below), it's safest to tell you what it's doing."
  1.7678 +msgstr ""
  1.7679 +
  1.7680 +#. type: Content of: <book><chapter><sect1><para>
  1.7681 +#: ../en/ch07-filenames.xml:92
  1.7682 +msgid ""
  1.7683 +"For commands that behave this way, you can silence them using the <option "
  1.7684 +"role=\"hg-opt-global\">-q</option> option.  You can also get them to print "
  1.7685 +"the name of every file, even those you've named explicitly, using the <option "
  1.7686 +"role=\"hg-opt-global\">-v</option> option."
  1.7687 +msgstr ""
  1.7688 +
  1.7689 +#. type: Content of: <book><chapter><sect1><title>
  1.7690 +#: ../en/ch07-filenames.xml:100
  1.7691 +msgid "Using patterns to identify files"
  1.7692 +msgstr ""
  1.7693 +
  1.7694 +#. type: Content of: <book><chapter><sect1><para>
  1.7695 +#: ../en/ch07-filenames.xml:102
  1.7696 +msgid ""
  1.7697 +"In addition to working with file and directory names, Mercurial lets you use "
  1.7698 +"<emphasis>patterns</emphasis> to identify files.  Mercurial's pattern "
  1.7699 +"handling is expressive."
  1.7700 +msgstr ""
  1.7701 +
  1.7702 +#. type: Content of: <book><chapter><sect1><para>
  1.7703 +#: ../en/ch07-filenames.xml:106
  1.7704 +msgid ""
  1.7705 +"On Unix-like systems (Linux, MacOS, etc.), the job of matching file names to "
  1.7706 +"patterns normally falls to the shell.  On these systems, you must explicitly "
  1.7707 +"tell Mercurial that a name is a pattern.  On Windows, the shell does not "
  1.7708 +"expand patterns, so Mercurial will automatically identify names that are "
  1.7709 +"patterns, and expand them for you."
  1.7710 +msgstr ""
  1.7711 +
  1.7712 +#. type: Content of: <book><chapter><sect1><para>
  1.7713 +#: ../en/ch07-filenames.xml:113
  1.7714 +msgid ""
  1.7715 +"To provide a pattern in place of a regular name on the command line, the "
  1.7716 +"mechanism is simple:"
  1.7717 +msgstr ""
  1.7718 +
  1.7719 +#. type: Content of: <book><chapter><sect1><para>
  1.7720 +#: ../en/ch07-filenames.xml:116
  1.7721 +msgid ""
  1.7722 +"That is, a pattern is identified by a short text string that says what kind "
  1.7723 +"of pattern this is, followed by a colon, followed by the actual pattern."
  1.7724 +msgstr ""
  1.7725 +
  1.7726 +#. type: Content of: <book><chapter><sect1><para>
  1.7727 +#: ../en/ch07-filenames.xml:120
  1.7728 +msgid ""
  1.7729 +"Mercurial supports two kinds of pattern syntax.  The most frequently used is "
  1.7730 +"called <literal>glob</literal>; this is the same kind of pattern matching "
  1.7731 +"used by the Unix shell, and should be familiar to Windows command prompt "
  1.7732 +"users, too."
  1.7733 +msgstr ""
  1.7734 +
  1.7735 +#. type: Content of: <book><chapter><sect1><para>
  1.7736 +#: ../en/ch07-filenames.xml:125
  1.7737 +msgid ""
  1.7738 +"When Mercurial does automatic pattern matching on Windows, it uses "
  1.7739 +"<literal>glob</literal> syntax.  You can thus omit the <quote><literal>glob:</"
  1.7740 +"literal></quote> prefix on Windows, but it's safe to use it, too."
  1.7741 +msgstr ""
  1.7742 +
  1.7743 +#. type: Content of: <book><chapter><sect1><para>
  1.7744 +#: ../en/ch07-filenames.xml:130
  1.7745 +msgid ""
  1.7746 +"The <literal>re</literal> syntax is more powerful; it lets you specify "
  1.7747 +"patterns using regular expressions, also known as regexps."
  1.7748 +msgstr ""
  1.7749 +
  1.7750 +#. type: Content of: <book><chapter><sect1><para>
  1.7751 +#: ../en/ch07-filenames.xml:134
  1.7752 +msgid ""
  1.7753 +"By the way, in the examples that follow, notice that I'm careful to wrap all "
  1.7754 +"of my patterns in quote characters, so that they won't get expanded by the "
  1.7755 +"shell before Mercurial sees them."
  1.7756 +msgstr ""
  1.7757 +
  1.7758 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.7759 +#: ../en/ch07-filenames.xml:140
  1.7760 +msgid "Shell-style <literal>glob</literal> patterns"
  1.7761 +msgstr ""
  1.7762 +
  1.7763 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7764 +#: ../en/ch07-filenames.xml:142
  1.7765 +msgid ""
  1.7766 +"This is an overview of the kinds of patterns you can use when you're matching "
  1.7767 +"on glob patterns."
  1.7768 +msgstr ""
  1.7769 +
  1.7770 +#
  1.7771 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7772 +#: ../en/ch07-filenames.xml:145
  1.7773 +msgid ""
  1.7774 +"The <quote><literal>*</literal></quote> character matches any string, within "
  1.7775 +"a single directory."
  1.7776 +msgstr ""
  1.7777 +
  1.7778 +#
  1.7779 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7780 +#: ../en/ch07-filenames.xml:150
  1.7781 +msgid ""
  1.7782 +"The <quote><literal>**</literal></quote> pattern matches any string, and "
  1.7783 +"crosses directory boundaries.  It's not a standard Unix glob token, but it's "
  1.7784 +"accepted by several popular Unix shells, and is very useful."
  1.7785 +msgstr ""
  1.7786 +
  1.7787 +#
  1.7788 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7789 +#: ../en/ch07-filenames.xml:157
  1.7790 +msgid ""
  1.7791 +"The <quote><literal>?</literal></quote> pattern matches any single character."
  1.7792 +msgstr ""
  1.7793 +
  1.7794 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7795 +#: ../en/ch07-filenames.xml:162
  1.7796 +msgid ""
  1.7797 +"The <quote><literal>[</literal></quote> character begins a "
  1.7798 +"<emphasis>character class</emphasis>.  This matches any single character "
  1.7799 +"within the class.  The class ends with a <quote><literal>]</literal></quote> "
  1.7800 +"character.  A class may contain multiple <emphasis>range</emphasis>s of the "
  1.7801 +"form <quote><literal>a-f</literal></quote>, which is shorthand for "
  1.7802 +"<quote><literal>abcdef</literal></quote>."
  1.7803 +msgstr ""
  1.7804 +
  1.7805 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7806 +#: ../en/ch07-filenames.xml:172
  1.7807 +msgid ""
  1.7808 +"If the first character after the <quote><literal>[</literal></quote> in a "
  1.7809 +"character class is a <quote><literal>!</literal></quote>, it "
  1.7810 +"<emphasis>negates</emphasis> the class, making it match any single character "
  1.7811 +"not in the class."
  1.7812 +msgstr ""
  1.7813 +
  1.7814 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7815 +#: ../en/ch07-filenames.xml:178
  1.7816 +msgid ""
  1.7817 +"A <quote><literal>{</literal></quote> begins a group of subpatterns, where "
  1.7818 +"the whole group matches if any subpattern in the group matches.  The "
  1.7819 +"<quote><literal>,</literal></quote> character separates subpatterns, and "
  1.7820 +"<quote><literal>}</literal></quote> ends the group."
  1.7821 +msgstr ""
  1.7822 +
  1.7823 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.7824 +#: ../en/ch07-filenames.xml:187
  1.7825 +msgid "Watch out!"
  1.7826 +msgstr ""
  1.7827 +
  1.7828 +#
  1.7829 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.7830 +#: ../en/ch07-filenames.xml:189
  1.7831 +msgid ""
  1.7832 +"Don't forget that if you want to match a pattern in any directory, you should "
  1.7833 +"not be using the <quote><literal>*</literal></quote> match-any token, as this "
  1.7834 +"will only match within one directory.  Instead, use the <quote><literal>**</"
  1.7835 +"literal></quote> token.  This small example illustrates the difference "
  1.7836 +"between the two."
  1.7837 +msgstr ""
  1.7838 +
  1.7839 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.7840 +#: ../en/ch07-filenames.xml:201
  1.7841 +msgid "Regular expression matching with <literal>re</literal> patterns"
  1.7842 +msgstr ""
  1.7843 +
  1.7844 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7845 +#: ../en/ch07-filenames.xml:204
  1.7846 +msgid ""
  1.7847 +"Mercurial accepts the same regular expression syntax as the Python "
  1.7848 +"programming language (it uses Python's regexp engine internally). This is "
  1.7849 +"based on the Perl language's regexp syntax, which is the most popular dialect "
  1.7850 +"in use (it's also used in Java, for example)."
  1.7851 +msgstr ""
  1.7852 +
  1.7853 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7854 +#: ../en/ch07-filenames.xml:210
  1.7855 +msgid ""
  1.7856 +"I won't discuss Mercurial's regexp dialect in any detail here, as regexps are "
  1.7857 +"not often used.  Perl-style regexps are in any case already exhaustively "
  1.7858 +"documented on a multitude of web sites, and in many books.  Instead, I will "
  1.7859 +"focus here on a few things you should know if you find yourself needing to "
  1.7860 +"use regexps with Mercurial."
  1.7861 +msgstr ""
  1.7862 +
  1.7863 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7864 +#: ../en/ch07-filenames.xml:217
  1.7865 +msgid ""
  1.7866 +"A regexp is matched against an entire file name, relative to the root of the "
  1.7867 +"repository.  In other words, even if you're already in subbdirectory "
  1.7868 +"<filename class=\"directory\">foo</filename>, if you want to match files "
  1.7869 +"under this directory, your pattern must start with <quote><literal>foo/</"
  1.7870 +"literal></quote>."
  1.7871 +msgstr ""
  1.7872 +
  1.7873 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.7874 +#: ../en/ch07-filenames.xml:224
  1.7875 +msgid ""
  1.7876 +"One thing to note, if you're familiar with Perl-style regexps, is that "
  1.7877 +"Mercurial's are <emphasis>rooted</emphasis>.  That is, a regexp starts "
  1.7878 +"matching against the beginning of a string; it doesn't look for a match "
  1.7879 +"anywhere within the string.  To match anywhere in a string, start your "
  1.7880 +"pattern with <quote><literal>.*</literal></quote>."
  1.7881 +msgstr ""
  1.7882 +
  1.7883 +#. type: Content of: <book><chapter><sect1><title>
  1.7884 +#: ../en/ch07-filenames.xml:234
  1.7885 +msgid "Filtering files"
  1.7886 +msgstr ""
  1.7887 +
  1.7888 +#. type: Content of: <book><chapter><sect1><para>
  1.7889 +#: ../en/ch07-filenames.xml:236
  1.7890 +msgid ""
  1.7891 +"Not only does Mercurial give you a variety of ways to specify files; it lets "
  1.7892 +"you further winnow those files using <emphasis>filters</emphasis>.  Commands "
  1.7893 +"that work with file names accept two filtering options."
  1.7894 +msgstr ""
  1.7895 +
  1.7896 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.7897 +#: ../en/ch07-filenames.xml:241
  1.7898 +msgid ""
  1.7899 +"<option role=\"hg-opt-global\">-I</option>, or <option role=\"hg-opt-global"
  1.7900 +"\">--include</option>, lets you specify a pattern that file names must match "
  1.7901 +"in order to be processed."
  1.7902 +msgstr ""
  1.7903 +
  1.7904 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.7905 +#: ../en/ch07-filenames.xml:246
  1.7906 +msgid ""
  1.7907 +"<option role=\"hg-opt-global\">-X</option>, or <option role=\"hg-opt-global"
  1.7908 +"\">--exclude</option>, gives you a way to <emphasis>avoid</emphasis> "
  1.7909 +"processing files, if they match this pattern."
  1.7910 +msgstr ""
  1.7911 +
  1.7912 +#. type: Content of: <book><chapter><sect1><para>
  1.7913 +#: ../en/ch07-filenames.xml:251
  1.7914 +msgid ""
  1.7915 +"You can provide multiple <option role=\"hg-opt-global\">-I</option> and "
  1.7916 +"<option role=\"hg-opt-global\">-X</option> options on the command line, and "
  1.7917 +"intermix them as you please.  Mercurial interprets the patterns you provide "
  1.7918 +"using glob syntax by default (but you can use regexps if you need to)."
  1.7919 +msgstr ""
  1.7920 +
  1.7921 +#. type: Content of: <book><chapter><sect1><para>
  1.7922 +#: ../en/ch07-filenames.xml:258
  1.7923 +msgid ""
  1.7924 +"You can read a <option role=\"hg-opt-global\">-I</option> filter as "
  1.7925 +"<quote>process only the files that match this filter</quote>."
  1.7926 +msgstr ""
  1.7927 +
  1.7928 +#. type: Content of: <book><chapter><sect1><para>
  1.7929 +#: ../en/ch07-filenames.xml:264
  1.7930 +msgid ""
  1.7931 +"The <option role=\"hg-opt-global\">-X</option> filter is best read as "
  1.7932 +"<quote>process only the files that don't match this pattern</quote>."
  1.7933 +msgstr ""
  1.7934 +
  1.7935 +#. type: Content of: <book><chapter><sect1><title>
  1.7936 +#: ../en/ch07-filenames.xml:272
  1.7937 +msgid "Ignoring unwanted files and directories"
  1.7938 +msgstr ""
  1.7939 +
  1.7940 +#. type: Content of: <book><chapter><sect1><para>
  1.7941 +#: ../en/ch07-filenames.xml:274
  1.7942 +msgid "XXX."
  1.7943 +msgstr ""
  1.7944 +
  1.7945 +#. type: Content of: <book><chapter><sect1><title>
  1.7946 +#: ../en/ch07-filenames.xml:278
  1.7947 +msgid "Case sensitivity"
  1.7948 +msgstr ""
  1.7949 +
  1.7950 +#. type: Content of: <book><chapter><sect1><para>
  1.7951 +#: ../en/ch07-filenames.xml:280
  1.7952 +msgid ""
  1.7953 +"If you're working in a mixed development environment that contains both Linux "
  1.7954 +"(or other Unix) systems and Macs or Windows systems, you should keep in the "
  1.7955 +"back of your mind the knowledge that they treat the case (<quote>N</quote> "
  1.7956 +"versus <quote>n</quote>) of file names in incompatible ways.  This is not "
  1.7957 +"very likely to affect you, and it's easy to deal with if it does, but it "
  1.7958 +"could surprise you if you don't know about it."
  1.7959 +msgstr ""
  1.7960 +
  1.7961 +#. type: Content of: <book><chapter><sect1><para>
  1.7962 +#: ../en/ch07-filenames.xml:289
  1.7963 +msgid ""
  1.7964 +"Operating systems and filesystems differ in the way they handle the "
  1.7965 +"<emphasis>case</emphasis> of characters in file and directory names.  There "
  1.7966 +"are three common ways to handle case in names."
  1.7967 +msgstr ""
  1.7968 +
  1.7969 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.7970 +#: ../en/ch07-filenames.xml:294
  1.7971 +msgid ""
  1.7972 +"Completely case insensitive.  Uppercase and lowercase versions of a letter "
  1.7973 +"are treated as identical, both when creating a file and during subsequent "
  1.7974 +"accesses.  This is common on older DOS-based systems."
  1.7975 +msgstr ""
  1.7976 +
  1.7977 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.7978 +#: ../en/ch07-filenames.xml:299
  1.7979 +msgid ""
  1.7980 +"Case preserving, but insensitive.  When a file or directory is created, the "
  1.7981 +"case of its name is stored, and can be retrieved and displayed by the "
  1.7982 +"operating system.  When an existing file is being looked up, its case is "
  1.7983 +"ignored.  This is the standard arrangement on Windows and MacOS.  The names "
  1.7984 +"<filename>foo</filename> and <filename>FoO</filename> identify the same "
  1.7985 +"file.  This treatment of uppercase and lowercase letters as interchangeable "
  1.7986 +"is also referred to as <emphasis>case folding</emphasis>."
  1.7987 +msgstr ""
  1.7988 +
  1.7989 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.7990 +#: ../en/ch07-filenames.xml:310
  1.7991 +msgid ""
  1.7992 +"Case sensitive.  The case of a name is significant at all times. The names "
  1.7993 +"<filename>foo</filename> and {FoO} identify different files.  This is the way "
  1.7994 +"Linux and Unix systems normally work."
  1.7995 +msgstr ""
  1.7996 +
  1.7997 +#. type: Content of: <book><chapter><sect1><para>
  1.7998 +#: ../en/ch07-filenames.xml:316
  1.7999 +msgid ""
  1.8000 +"On Unix-like systems, it is possible to have any or all of the above ways of "
  1.8001 +"handling case in action at once.  For example, if you use a USB thumb drive "
  1.8002 +"formatted with a FAT32 filesystem on a Linux system, Linux will handle names "
  1.8003 +"on that filesystem in a case preserving, but insensitive, way."
  1.8004 +msgstr ""
  1.8005 +
  1.8006 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8007 +#: ../en/ch07-filenames.xml:323
  1.8008 +msgid "Safe, portable repository storage"
  1.8009 +msgstr ""
  1.8010 +
  1.8011 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8012 +#: ../en/ch07-filenames.xml:325
  1.8013 +msgid ""
  1.8014 +"Mercurial's repository storage mechanism is <emphasis>case safe</emphasis>.  "
  1.8015 +"It translates file names so that they can be safely stored on both case "
  1.8016 +"sensitive and case insensitive filesystems.  This means that you can use "
  1.8017 +"normal file copying tools to transfer a Mercurial repository onto, for "
  1.8018 +"example, a USB thumb drive, and safely move that drive and repository back "
  1.8019 +"and forth between a Mac, a PC running Windows, and a Linux box."
  1.8020 +msgstr ""
  1.8021 +
  1.8022 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8023 +#: ../en/ch07-filenames.xml:336
  1.8024 +msgid "Detecting case conflicts"
  1.8025 +msgstr ""
  1.8026 +
  1.8027 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8028 +#: ../en/ch07-filenames.xml:338
  1.8029 +msgid ""
  1.8030 +"When operating in the working directory, Mercurial honours the naming policy "
  1.8031 +"of the filesystem where the working directory is located.  If the filesystem "
  1.8032 +"is case preserving, but insensitive, Mercurial will treat names that differ "
  1.8033 +"only in case as the same."
  1.8034 +msgstr ""
  1.8035 +
  1.8036 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8037 +#: ../en/ch07-filenames.xml:344
  1.8038 +msgid ""
  1.8039 +"An important aspect of this approach is that it is possible to commit a "
  1.8040 +"changeset on a case sensitive (typically Linux or Unix) filesystem that will "
  1.8041 +"cause trouble for users on case insensitive (usually Windows and MacOS) "
  1.8042 +"users.  If a Linux user commits changes to two files, one named "
  1.8043 +"<filename>myfile.c</filename> and the other named <filename>MyFile.C</"
  1.8044 +"filename>, they will be stored correctly in the repository.  And in the "
  1.8045 +"working directories of other Linux users, they will be correctly represented "
  1.8046 +"as separate files."
  1.8047 +msgstr ""
  1.8048 +
  1.8049 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8050 +#: ../en/ch07-filenames.xml:355
  1.8051 +msgid ""
  1.8052 +"If a Windows or Mac user pulls this change, they will not initially have a "
  1.8053 +"problem, because Mercurial's repository storage mechanism is case safe.  "
  1.8054 +"However, once they try to <command role=\"hg-cmd\">hg update</command> the "
  1.8055 +"working directory to that changeset, or <command role=\"hg-cmd\">hg merge</"
  1.8056 +"command> with that changeset, Mercurial will spot the conflict between the "
  1.8057 +"two file names that the filesystem would treat as the same, and forbid the "
  1.8058 +"update or merge from occurring."
  1.8059 +msgstr ""
  1.8060 +
  1.8061 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8062 +#: ../en/ch07-filenames.xml:367
  1.8063 +msgid "Fixing a case conflict"
  1.8064 +msgstr ""
  1.8065 +
  1.8066 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8067 +#: ../en/ch07-filenames.xml:369
  1.8068 +msgid ""
  1.8069 +"If you are using Windows or a Mac in a mixed environment where some of your "
  1.8070 +"collaborators are using Linux or Unix, and Mercurial reports a case folding "
  1.8071 +"conflict when you try to <command role=\"hg-cmd\">hg update</command> or "
  1.8072 +"<command role=\"hg-cmd\">hg merge</command>, the procedure to fix the problem "
  1.8073 +"is simple."
  1.8074 +msgstr ""
  1.8075 +
  1.8076 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8077 +#: ../en/ch07-filenames.xml:376
  1.8078 +msgid ""
  1.8079 +"Just find a nearby Linux or Unix box, clone the problem repository onto it, "
  1.8080 +"and use Mercurial's <command role=\"hg-cmd\">hg rename</command> command to "
  1.8081 +"change the names of any offending files or directories so that they will no "
  1.8082 +"longer cause case folding conflicts.  Commit this change, <command role=\"hg-"
  1.8083 +"cmd\">hg pull</command> or <command role=\"hg-cmd\">hg push</command> it "
  1.8084 +"across to your Windows or MacOS system, and <command role=\"hg-cmd\">hg "
  1.8085 +"update</command> to the revision with the non-conflicting names."
  1.8086 +msgstr ""
  1.8087 +
  1.8088 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8089 +#: ../en/ch07-filenames.xml:386
  1.8090 +msgid ""
  1.8091 +"The changeset with case-conflicting names will remain in your project's "
  1.8092 +"history, and you still won't be able to <command role=\"hg-cmd\">hg update</"
  1.8093 +"command> your working directory to that changeset on a Windows or MacOS "
  1.8094 +"system, but you can continue development unimpeded."
  1.8095 +msgstr ""
  1.8096 +
  1.8097 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
  1.8098 +#: ../en/ch07-filenames.xml:393
  1.8099 +msgid ""
  1.8100 +"Prior to version 0.9.3, Mercurial did not use a case safe repository storage "
  1.8101 +"mechanism, and did not detect case folding conflicts.  If you are using an "
  1.8102 +"older version of Mercurial on Windows or MacOS, I strongly recommend that you "
  1.8103 +"upgrade."
  1.8104 +msgstr ""
  1.8105 +
  1.8106 +#. type: Content of: <book><chapter><title>
  1.8107 +#: ../en/ch08-branch.xml:5
  1.8108 +msgid "Managing releases and branchy development"
  1.8109 +msgstr "发布管理与分支开发"
  1.8110 +
  1.8111 +#. type: Content of: <book><chapter><para>
  1.8112 +#: ../en/ch08-branch.xml:7
  1.8113 +msgid ""
  1.8114 +"Mercurial provides several mechanisms for you to manage a project that is "
  1.8115 +"making progress on multiple fronts at once.  To understand these mechanisms, "
  1.8116 +"let's first take a brief look at a fairly normal software project structure."
  1.8117 +msgstr ""
  1.8118 +
  1.8119 +#. type: Content of: <book><chapter><para>
  1.8120 +#: ../en/ch08-branch.xml:12
  1.8121 +msgid ""
  1.8122 +"Many software projects issue periodic <quote>major</quote> releases that "
  1.8123 +"contain substantial new features.  In parallel, they may issue <quote>minor</"
  1.8124 +"quote> releases.  These are usually identical to the major releases off which "
  1.8125 +"they're based, but with a few bugs fixed."
  1.8126 +msgstr ""
  1.8127 +
  1.8128 +#. type: Content of: <book><chapter><para>
  1.8129 +#: ../en/ch08-branch.xml:18
  1.8130 +msgid ""
  1.8131 +"In this chapter, we'll start by talking about how to keep records of project "
  1.8132 +"milestones such as releases.  We'll then continue on to talk about the flow "
  1.8133 +"of work between different phases of a project, and how Mercurial can help you "
  1.8134 +"to isolate and manage this work."
  1.8135 +msgstr ""
  1.8136 +
  1.8137 +#. type: Content of: <book><chapter><sect1><title>
  1.8138 +#: ../en/ch08-branch.xml:25
  1.8139 +msgid "Giving a persistent name to a revision"
  1.8140 +msgstr ""
  1.8141 +
  1.8142 +#. type: Content of: <book><chapter><sect1><para>
  1.8143 +#: ../en/ch08-branch.xml:27
  1.8144 +msgid ""
  1.8145 +"Once you decide that you'd like to call a particular revision a "
  1.8146 +"<quote>release</quote>, it's a good idea to record the identity of that "
  1.8147 +"revision. This will let you reproduce that release at a later date, for "
  1.8148 +"whatever purpose you might need at the time (reproducing a bug, porting to a "
  1.8149 +"new platform, etc).  &interaction.tag.init;"
  1.8150 +msgstr ""
  1.8151 +
  1.8152 +#
  1.8153 +#. type: Content of: <book><chapter><sect1><para>
  1.8154 +#: ../en/ch08-branch.xml:34
  1.8155 +msgid ""
  1.8156 +"Mercurial lets you give a permanent name to any revision using the <command "
  1.8157 +"role=\"hg-cmd\">hg tag</command> command.  Not surprisingly, these names are "
  1.8158 +"called <quote>tags</quote>."
  1.8159 +msgstr ""
  1.8160 +
  1.8161 +#. type: Content of: <book><chapter><sect1><para>
  1.8162 +#: ../en/ch08-branch.xml:40
  1.8163 +msgid ""
  1.8164 +"A tag is nothing more than a <quote>symbolic name</quote> for a revision.  "
  1.8165 +"Tags exist purely for your convenience, so that you have a handy permanent "
  1.8166 +"way to refer to a revision; Mercurial doesn't interpret the tag names you use "
  1.8167 +"in any way.  Neither does Mercurial place any restrictions on the name of a "
  1.8168 +"tag, beyond a few that are necessary to ensure that a tag can be parsed "
  1.8169 +"unambiguously.  A tag name cannot contain any of the following characters:"
  1.8170 +msgstr ""
  1.8171 +
  1.8172 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.8173 +#: ../en/ch08-branch.xml:49
  1.8174 +msgid "Colon (ASCII 58, <quote><literal>:</literal></quote>)"
  1.8175 +msgstr ""
  1.8176 +
  1.8177 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.8178 +#: ../en/ch08-branch.xml:52
  1.8179 +msgid "Carriage return (ASCII 13, <quote><literal>\\r</literal></quote>)"
  1.8180 +msgstr ""
  1.8181 +
  1.8182 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.8183 +#: ../en/ch08-branch.xml:55
  1.8184 +msgid "Newline (ASCII 10, <quote><literal>\\n</literal></quote>)"
  1.8185 +msgstr ""
  1.8186 +
  1.8187 +#. type: Content of: <book><chapter><sect1><para>
  1.8188 +#: ../en/ch08-branch.xml:59
  1.8189 +msgid ""
  1.8190 +"You can use the <command role=\"hg-cmd\">hg tags</command> command to display "
  1.8191 +"the tags present in your repository.  In the output, each tagged revision is "
  1.8192 +"identified first by its name, then by revision number, and finally by the "
  1.8193 +"unique hash of the revision."
  1.8194 +msgstr ""
  1.8195 +
  1.8196 +#. type: Content of: <book><chapter><sect1><para>
  1.8197 +#: ../en/ch08-branch.xml:67
  1.8198 +msgid ""
  1.8199 +"Notice that <literal>tip</literal> is listed in the output of <command role="
  1.8200 +"\"hg-cmd\">hg tags</command>.  The <literal>tip</literal> tag is a special "
  1.8201 +"<quote>floating</quote> tag, which always identifies the newest revision in "
  1.8202 +"the repository."
  1.8203 +msgstr ""
  1.8204 +
  1.8205 +#. type: Content of: <book><chapter><sect1><para>
  1.8206 +#: ../en/ch08-branch.xml:73
  1.8207 +msgid ""
  1.8208 +"In the output of the <command role=\"hg-cmd\">hg tags</command> command, tags "
  1.8209 +"are listed in reverse order, by revision number.  This usually means that "
  1.8210 +"recent tags are listed before older tags.  It also means that <literal>tip</"
  1.8211 +"literal> is always going to be the first tag listed in the output of <command "
  1.8212 +"role=\"hg-cmd\">hg tags</command>."
  1.8213 +msgstr ""
  1.8214 +
  1.8215 +#. type: Content of: <book><chapter><sect1><para>
  1.8216 +#: ../en/ch08-branch.xml:80
  1.8217 +msgid ""
  1.8218 +"When you run <command role=\"hg-cmd\">hg log</command>, if it displays a "
  1.8219 +"revision that has tags associated with it, it will print those tags."
  1.8220 +msgstr ""
  1.8221 +
  1.8222 +#
  1.8223 +#. type: Content of: <book><chapter><sect1><para>
  1.8224 +#: ../en/ch08-branch.xml:86
  1.8225 +msgid ""
  1.8226 +"Any time you need to provide a revision ID to a Mercurial command, the "
  1.8227 +"command will accept a tag name in its place.  Internally, Mercurial will "
  1.8228 +"translate your tag name into the corresponding revision ID, then use that."
  1.8229 +msgstr ""
  1.8230 +
  1.8231 +#. type: Content of: <book><chapter><sect1><para>
  1.8232 +#: ../en/ch08-branch.xml:93
  1.8233 +msgid ""
  1.8234 +"There's no limit on the number of tags you can have in a repository, or on "
  1.8235 +"the number of tags that a single revision can have.  As a practical matter, "
  1.8236 +"it's not a great idea to have <quote>too many</quote> (a number which will "
  1.8237 +"vary from project to project), simply because tags are supposed to help you "
  1.8238 +"to find revisions.  If you have lots of tags, the ease of using them to "
  1.8239 +"identify revisions diminishes rapidly."
  1.8240 +msgstr ""
  1.8241 +
  1.8242 +#. type: Content of: <book><chapter><sect1><para>
  1.8243 +#: ../en/ch08-branch.xml:101
  1.8244 +msgid ""
  1.8245 +"For example, if your project has milestones as frequent as every few days, "
  1.8246 +"it's perfectly reasonable to tag each one of those.  But if you have a "
  1.8247 +"continuous build system that makes sure every revision can be built cleanly, "
  1.8248 +"you'd be introducing a lot of noise if you were to tag every clean build.  "
  1.8249 +"Instead, you could tag failed builds (on the assumption that they're rare!), "
  1.8250 +"or simply not use tags to track buildability."
  1.8251 +msgstr ""
  1.8252 +
  1.8253 +#. type: Content of: <book><chapter><sect1><para>
  1.8254 +#: ../en/ch08-branch.xml:109
  1.8255 +msgid ""
  1.8256 +"If you want to remove a tag that you no longer want, use <command role=\"hg-"
  1.8257 +"cmd\">hg tag --remove</command>."
  1.8258 +msgstr ""
  1.8259 +
  1.8260 +#. type: Content of: <book><chapter><sect1><para>
  1.8261 +#: ../en/ch08-branch.xml:114
  1.8262 +msgid ""
  1.8263 +"You can also modify a tag at any time, so that it identifies a different "
  1.8264 +"revision, by simply issuing a new <command role=\"hg-cmd\">hg tag</command> "
  1.8265 +"command. You'll have to use the <option role=\"hg-opt-tag\">-f</option> "
  1.8266 +"option to tell Mercurial that you <emphasis>really</emphasis> want to update "
  1.8267 +"the tag."
  1.8268 +msgstr ""
  1.8269 +
  1.8270 +#. type: Content of: <book><chapter><sect1><para>
  1.8271 +#: ../en/ch08-branch.xml:123
  1.8272 +msgid ""
  1.8273 +"There will still be a permanent record of the previous identity of the tag, "
  1.8274 +"but Mercurial will no longer use it.  There's thus no penalty to tagging the "
  1.8275 +"wrong revision; all you have to do is turn around and tag the correct "
  1.8276 +"revision once you discover your error."
  1.8277 +msgstr ""
  1.8278 +
  1.8279 +#
  1.8280 +#. type: Content of: <book><chapter><sect1><para>
  1.8281 +#: ../en/ch08-branch.xml:129
  1.8282 +msgid ""
  1.8283 +"Mercurial stores tags in a normal revision-controlled file in your "
  1.8284 +"repository.  If you've created any tags, you'll find them in a file named "
  1.8285 +"<filename role=\"special\">.hgtags</filename>.  When you run the <command "
  1.8286 +"role=\"hg-cmd\">hg tag</command> command, Mercurial modifies this file, then "
  1.8287 +"automatically commits the change to it.  This means that every time you run "
  1.8288 +"<command role=\"hg-cmd\">hg tag</command>, you'll see a corresponding "
  1.8289 +"changeset in the output of <command role=\"hg-cmd\">hg log</command>."
  1.8290 +msgstr ""
  1.8291 +
  1.8292 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8293 +#: ../en/ch08-branch.xml:142
  1.8294 +msgid "Handling tag conflicts during a merge"
  1.8295 +msgstr ""
  1.8296 +
  1.8297 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8298 +#: ../en/ch08-branch.xml:144
  1.8299 +msgid ""
  1.8300 +"You won't often need to care about the <filename role=\"special\">.hgtags</"
  1.8301 +"filename> file, but it sometimes makes its presence known during a merge.  "
  1.8302 +"The format of the file is simple: it consists of a series of lines.  Each "
  1.8303 +"line starts with a changeset hash, followed by a space, followed by the name "
  1.8304 +"of a tag."
  1.8305 +msgstr ""
  1.8306 +
  1.8307 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8308 +#: ../en/ch08-branch.xml:151
  1.8309 +msgid ""
  1.8310 +"If you're resolving a conflict in the <filename role=\"special\">.hgtags</"
  1.8311 +"filename> file during a merge, there's one twist to modifying the <filename "
  1.8312 +"role=\"special\">.hgtags</filename> file: when Mercurial is parsing the tags "
  1.8313 +"in a repository, it <emphasis>never</emphasis> reads the working copy of the "
  1.8314 +"<filename role=\"special\">.hgtags</filename> file.  Instead, it reads the "
  1.8315 +"<emphasis>most recently committed</emphasis> revision of the file."
  1.8316 +msgstr ""
  1.8317 +
  1.8318 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8319 +#: ../en/ch08-branch.xml:161
  1.8320 +msgid ""
  1.8321 +"An unfortunate consequence of this design is that you can't actually verify "
  1.8322 +"that your merged <filename role=\"special\">.hgtags</filename> file is "
  1.8323 +"correct until <emphasis>after</emphasis> you've committed a change.  So if "
  1.8324 +"you find yourself resolving a conflict on <filename role=\"special\">.hgtags</"
  1.8325 +"filename> during a merge, be sure to run <command role=\"hg-cmd\">hg tags</"
  1.8326 +"command> after you commit.  If it finds an error in the <filename role="
  1.8327 +"\"special\">.hgtags</filename> file, it will report the location of the "
  1.8328 +"error, which you can then fix and commit.  You should then run <command role="
  1.8329 +"\"hg-cmd\">hg tags</command> again, just to be sure that your fix is correct."
  1.8330 +msgstr ""
  1.8331 +
  1.8332 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8333 +#: ../en/ch08-branch.xml:176
  1.8334 +msgid "Tags and cloning"
  1.8335 +msgstr ""
  1.8336 +
  1.8337 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8338 +#: ../en/ch08-branch.xml:178
  1.8339 +msgid ""
  1.8340 +"You may have noticed that the <command role=\"hg-cmd\">hg clone</command> "
  1.8341 +"command has a <option role=\"hg-opt-clone\">-r</option> option that lets you "
  1.8342 +"clone an exact copy of the repository as of a particular changeset.  The new "
  1.8343 +"clone will not contain any project history that comes after the revision you "
  1.8344 +"specified.  This has an interaction with tags that can surprise the unwary."
  1.8345 +msgstr ""
  1.8346 +
  1.8347 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8348 +#: ../en/ch08-branch.xml:186
  1.8349 +msgid ""
  1.8350 +"Recall that a tag is stored as a revision to the <filename role=\"special\">."
  1.8351 +"hgtags</filename> file, so that when you create a tag, the changeset in which "
  1.8352 +"it's recorded necessarily refers to an older changeset.  When you run "
  1.8353 +"<command role=\"hg-cmd\">hg clone -r foo</command> to clone a repository as "
  1.8354 +"of tag <literal>foo</literal>, the new clone <emphasis>will not contain the "
  1.8355 +"history that created the tag</emphasis> that you used to clone the "
  1.8356 +"repository.  The result is that you'll get exactly the right subset of the "
  1.8357 +"project's history in the new repository, but <emphasis>not</emphasis> the tag "
  1.8358 +"you might have expected."
  1.8359 +msgstr ""
  1.8360 +
  1.8361 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8362 +#: ../en/ch08-branch.xml:201
  1.8363 +msgid "When permanent tags are too much"
  1.8364 +msgstr ""
  1.8365 +
  1.8366 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8367 +#: ../en/ch08-branch.xml:203
  1.8368 +msgid ""
  1.8369 +"Since Mercurial's tags are revision controlled and carried around with a "
  1.8370 +"project's history, everyone you work with will see the tags you create.  But "
  1.8371 +"giving names to revisions has uses beyond simply noting that revision "
  1.8372 +"<literal>4237e45506ee</literal> is really <literal>v2.0.2</literal>.  If "
  1.8373 +"you're trying to track down a subtle bug, you might want a tag to remind you "
  1.8374 +"of something like <quote>Anne saw the symptoms with this revision</quote>."
  1.8375 +msgstr ""
  1.8376 +
  1.8377 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8378 +#: ../en/ch08-branch.xml:213
  1.8379 +msgid ""
  1.8380 +"For cases like this, what you might want to use are <emphasis>local</"
  1.8381 +"emphasis> tags. You can create a local tag with the <option role=\"hg-opt-tag"
  1.8382 +"\">-l</option> option to the <command role=\"hg-cmd\">hg tag</command> "
  1.8383 +"command.  This will store the tag in a file called <filename role=\"special"
  1.8384 +"\">.hg/localtags</filename>.  Unlike <filename role=\"special\">.hgtags</"
  1.8385 +"filename>, <filename role=\"special\">.hg/localtags</filename> is not "
  1.8386 +"revision controlled.  Any tags you create using <option role=\"hg-opt-tag\">-"
  1.8387 +"l</option> remain strictly local to the repository you're currently working "
  1.8388 +"in."
  1.8389 +msgstr ""
  1.8390 +
  1.8391 +#. type: Content of: <book><chapter><sect1><title>
  1.8392 +#: ../en/ch08-branch.xml:228
  1.8393 +msgid "The flow of changes&emdash;big picture vs. little"
  1.8394 +msgstr ""
  1.8395 +
  1.8396 +#. type: Content of: <book><chapter><sect1><para>
  1.8397 +#: ../en/ch08-branch.xml:230
  1.8398 +msgid ""
  1.8399 +"To return to the outline I sketched at the beginning of a chapter, let's "
  1.8400 +"think about a project that has multiple concurrent pieces of work under "
  1.8401 +"development at once."
  1.8402 +msgstr ""
  1.8403 +
  1.8404 +#. type: Content of: <book><chapter><sect1><para>
  1.8405 +#: ../en/ch08-branch.xml:234
  1.8406 +msgid ""
  1.8407 +"There might be a push for a new <quote>main</quote> release; a new minor "
  1.8408 +"bugfix release to the last main release; and an unexpected <quote>hot fix</"
  1.8409 +"quote> to an old release that is now in maintenance mode."
  1.8410 +msgstr ""
  1.8411 +
  1.8412 +#. type: Content of: <book><chapter><sect1><para>
  1.8413 +#: ../en/ch08-branch.xml:239
  1.8414 +msgid ""
  1.8415 +"The usual way people refer to these different concurrent directions of "
  1.8416 +"development is as <quote>branches</quote>.  However, we've already seen "
  1.8417 +"numerous times that Mercurial treats <emphasis>all of history</emphasis> as a "
  1.8418 +"series of branches and merges.  Really, what we have here is two ideas that "
  1.8419 +"are peripherally related, but which happen to share a name."
  1.8420 +msgstr ""
  1.8421 +
  1.8422 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.8423 +#: ../en/ch08-branch.xml:246
  1.8424 +msgid ""
  1.8425 +"<quote>Big picture</quote> branches represent the sweep of a project's "
  1.8426 +"evolution; people give them names, and talk about them in conversation."
  1.8427 +msgstr ""
  1.8428 +
  1.8429 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.8430 +#: ../en/ch08-branch.xml:250
  1.8431 +msgid ""
  1.8432 +"<quote>Little picture</quote> branches are artefacts of the day-to-day "
  1.8433 +"activity of developing and merging changes.  They expose the narrative of how "
  1.8434 +"the code was developed."
  1.8435 +msgstr ""
  1.8436 +
  1.8437 +#. type: Content of: <book><chapter><sect1><title>
  1.8438 +#: ../en/ch08-branch.xml:258
  1.8439 +msgid "Managing big-picture branches in repositories"
  1.8440 +msgstr ""
  1.8441 +
  1.8442 +#. type: Content of: <book><chapter><sect1><para>
  1.8443 +#: ../en/ch08-branch.xml:260
  1.8444 +msgid ""
  1.8445 +"The easiest way to isolate a <quote>big picture</quote> branch in Mercurial "
  1.8446 +"is in a dedicated repository.  If you have an existing shared "
  1.8447 +"repository&emdash;let's call it <literal>myproject</literal>&emdash;that "
  1.8448 +"reaches a <quote>1.0</quote> milestone, you can start to prepare for future "
  1.8449 +"maintenance releases on top of version 1.0 by tagging the revision from which "
  1.8450 +"you prepared the 1.0 release."
  1.8451 +msgstr ""
  1.8452 +
  1.8453 +#. type: Content of: <book><chapter><sect1><para>
  1.8454 +#: ../en/ch08-branch.xml:270
  1.8455 +msgid ""
  1.8456 +"You can then clone a new shared <literal>myproject-1.0.1</literal> repository "
  1.8457 +"as of that tag."
  1.8458 +msgstr ""
  1.8459 +
  1.8460 +#. type: Content of: <book><chapter><sect1><para>
  1.8461 +#: ../en/ch08-branch.xml:276
  1.8462 +msgid ""
  1.8463 +"Afterwards, if someone needs to work on a bug fix that ought to go into an "
  1.8464 +"upcoming 1.0.1 minor release, they clone the <literal>myproject-1.0.1</"
  1.8465 +"literal> repository, make their changes, and push them back."
  1.8466 +msgstr ""
  1.8467 +
  1.8468 +#. type: Content of: <book><chapter><sect1><para>
  1.8469 +#: ../en/ch08-branch.xml:283
  1.8470 +msgid ""
  1.8471 +"Meanwhile, development for the next major release can continue, isolated and "
  1.8472 +"unabated, in the <literal>myproject</literal> repository."
  1.8473 +msgstr ""
  1.8474 +
  1.8475 +#. type: Content of: <book><chapter><sect1><title>
  1.8476 +#: ../en/ch08-branch.xml:291
  1.8477 +msgid "Don't repeat yourself: merging across branches"
  1.8478 +msgstr ""
  1.8479 +
  1.8480 +#. type: Content of: <book><chapter><sect1><para>
  1.8481 +#: ../en/ch08-branch.xml:293
  1.8482 +msgid ""
  1.8483 +"In many cases, if you have a bug to fix on a maintenance branch, the chances "
  1.8484 +"are good that the bug exists on your project's main branch (and possibly "
  1.8485 +"other maintenance branches, too).  It's a rare developer who wants to fix the "
  1.8486 +"same bug multiple times, so let's look at a few ways that Mercurial can help "
  1.8487 +"you to manage these bugfixes without duplicating your work."
  1.8488 +msgstr ""
  1.8489 +
  1.8490 +#. type: Content of: <book><chapter><sect1><para>
  1.8491 +#: ../en/ch08-branch.xml:301
  1.8492 +msgid ""
  1.8493 +"In the simplest instance, all you need to do is pull changes from your "
  1.8494 +"maintenance branch into your local clone of the target branch."
  1.8495 +msgstr ""
  1.8496 +
  1.8497 +#. type: Content of: <book><chapter><sect1><para>
  1.8498 +#: ../en/ch08-branch.xml:307
  1.8499 +msgid ""
  1.8500 +"You'll then need to merge the heads of the two branches, and push back to the "
  1.8501 +"main branch."
  1.8502 +msgstr ""
  1.8503 +
  1.8504 +#. type: Content of: <book><chapter><sect1><title>
  1.8505 +#: ../en/ch08-branch.xml:314
  1.8506 +msgid "Naming branches within one repository"
  1.8507 +msgstr ""
  1.8508 +
  1.8509 +#. type: Content of: <book><chapter><sect1><para>
  1.8510 +#: ../en/ch08-branch.xml:316
  1.8511 +msgid ""
  1.8512 +"In most instances, isolating branches in repositories is the right approach.  "
  1.8513 +"Its simplicity makes it easy to understand; and so it's hard to make "
  1.8514 +"mistakes.  There's a one-to-one relationship between branches you're working "
  1.8515 +"in and directories on your system.  This lets you use normal (non-Mercurial-"
  1.8516 +"aware)  tools to work on files within a branch/repository."
  1.8517 +msgstr ""
  1.8518 +
  1.8519 +#. type: Content of: <book><chapter><sect1><para>
  1.8520 +#: ../en/ch08-branch.xml:323
  1.8521 +msgid ""
  1.8522 +"If you're more in the <quote>power user</quote> category (<emphasis>and</"
  1.8523 +"emphasis> your collaborators are too), there is an alternative way of "
  1.8524 +"handling branches that you can consider.  I've already mentioned the human-"
  1.8525 +"level distinction between <quote>small picture</quote> and <quote>big "
  1.8526 +"picture</quote> branches.  While Mercurial works with multiple <quote>small "
  1.8527 +"picture</quote> branches in a repository all the time (for example after you "
  1.8528 +"pull changes in, but before you merge them), it can <emphasis>also</emphasis> "
  1.8529 +"work with multiple <quote>big picture</quote> branches."
  1.8530 +msgstr ""
  1.8531 +
  1.8532 +#. type: Content of: <book><chapter><sect1><para>
  1.8533 +#: ../en/ch08-branch.xml:334
  1.8534 +msgid ""
  1.8535 +"The key to working this way is that Mercurial lets you assign a persistent "
  1.8536 +"<emphasis>name</emphasis> to a branch.  There always exists a branch named "
  1.8537 +"<literal>default</literal>.  Even before you start naming branches yourself, "
  1.8538 +"you can find traces of the <literal>default</literal> branch if you look for "
  1.8539 +"them."
  1.8540 +msgstr ""
  1.8541 +
  1.8542 +#. type: Content of: <book><chapter><sect1><para>
  1.8543 +#: ../en/ch08-branch.xml:341
  1.8544 +msgid ""
  1.8545 +"As an example, when you run the <command role=\"hg-cmd\">hg commit</command> "
  1.8546 +"command, and it pops up your editor so that you can enter a commit message, "
  1.8547 +"look for a line that contains the text <quote><literal>HG: branch default</"
  1.8548 +"literal></quote> at the bottom. This is telling you that your commit will "
  1.8549 +"occur on the branch named <literal>default</literal>."
  1.8550 +msgstr ""
  1.8551 +
  1.8552 +#. type: Content of: <book><chapter><sect1><para>
  1.8553 +#: ../en/ch08-branch.xml:348
  1.8554 +msgid ""
  1.8555 +"To start working with named branches, use the <command role=\"hg-cmd\">hg "
  1.8556 +"branches</command> command.  This command lists the named branches already "
  1.8557 +"present in your repository, telling you which changeset is the tip of each."
  1.8558 +msgstr ""
  1.8559 +
  1.8560 +#. type: Content of: <book><chapter><sect1><para>
  1.8561 +#: ../en/ch08-branch.xml:355
  1.8562 +msgid ""
  1.8563 +"Since you haven't created any named branches yet, the only one that exists is "
  1.8564 +"<literal>default</literal>."
  1.8565 +msgstr ""
  1.8566 +
  1.8567 +#. type: Content of: <book><chapter><sect1><para>
  1.8568 +#: ../en/ch08-branch.xml:358
  1.8569 +msgid ""
  1.8570 +"To find out what the <quote>current</quote> branch is, run the <command role="
  1.8571 +"\"hg-cmd\">hg branch</command> command, giving it no arguments.  This tells "
  1.8572 +"you what branch the parent of the current changeset is on."
  1.8573 +msgstr ""
  1.8574 +
  1.8575 +#
  1.8576 +#. type: Content of: <book><chapter><sect1><para>
  1.8577 +#: ../en/ch08-branch.xml:365
  1.8578 +msgid ""
  1.8579 +"To create a new branch, run the <command role=\"hg-cmd\">hg branch</command> "
  1.8580 +"command again.  This time, give it one argument: the name of the branch you "
  1.8581 +"want to create."
  1.8582 +msgstr ""
  1.8583 +
  1.8584 +#. type: Content of: <book><chapter><sect1><para>
  1.8585 +#: ../en/ch08-branch.xml:371
  1.8586 +msgid ""
  1.8587 +"After you've created a branch, you might wonder what effect the <command role="
  1.8588 +"\"hg-cmd\">hg branch</command> command has had.  What do the <command role="
  1.8589 +"\"hg-cmd\">hg status</command> and <command role=\"hg-cmd\">hg tip</command> "
  1.8590 +"commands report?"
  1.8591 +msgstr ""
  1.8592 +
  1.8593 +#. type: Content of: <book><chapter><sect1><para>
  1.8594 +#: ../en/ch08-branch.xml:378
  1.8595 +msgid ""
  1.8596 +"Nothing has changed in the working directory, and there's been no new history "
  1.8597 +"created.  As this suggests, running the <command role=\"hg-cmd\">hg branch</"
  1.8598 +"command> command has no permanent effect; it only tells Mercurial what branch "
  1.8599 +"name to use the <emphasis>next</emphasis> time you commit a changeset."
  1.8600 +msgstr ""
  1.8601 +
  1.8602 +#. type: Content of: <book><chapter><sect1><para>
  1.8603 +#: ../en/ch08-branch.xml:385
  1.8604 +msgid ""
  1.8605 +"When you commit a change, Mercurial records the name of the branch on which "
  1.8606 +"you committed.  Once you've switched from the <literal>default</literal> "
  1.8607 +"branch to another and committed, you'll see the name of the new branch show "
  1.8608 +"up in the output of <command role=\"hg-cmd\">hg log</command>, <command role="
  1.8609 +"\"hg-cmd\">hg tip</command>, and other commands that display the same kind of "
  1.8610 +"output."
  1.8611 +msgstr ""
  1.8612 +
  1.8613 +#. type: Content of: <book><chapter><sect1><para>
  1.8614 +#: ../en/ch08-branch.xml:395
  1.8615 +msgid ""
  1.8616 +"The <command role=\"hg-cmd\">hg log</command>-like commands will print the "
  1.8617 +"branch name of every changeset that's not on the <literal>default</literal> "
  1.8618 +"branch.  As a result, if you never use named branches, you'll never see this "
  1.8619 +"information."
  1.8620 +msgstr ""
  1.8621 +
  1.8622 +#. type: Content of: <book><chapter><sect1><para>
  1.8623 +#: ../en/ch08-branch.xml:400
  1.8624 +msgid ""
  1.8625 +"Once you've named a branch and committed a change with that name, every "
  1.8626 +"subsequent commit that descends from that change will inherit the same branch "
  1.8627 +"name.  You can change the name of a branch at any time, using the <command "
  1.8628 +"role=\"hg-cmd\">hg branch</command> command."
  1.8629 +msgstr ""
  1.8630 +
  1.8631 +#. type: Content of: <book><chapter><sect1><para>
  1.8632 +#: ../en/ch08-branch.xml:408
  1.8633 +msgid ""
  1.8634 +"In practice, this is something you won't do very often, as branch names tend "
  1.8635 +"to have fairly long lifetimes.  (This isn't a rule, just an observation.)"
  1.8636 +msgstr ""
  1.8637 +
  1.8638 +#. type: Content of: <book><chapter><sect1><title>
  1.8639 +#: ../en/ch08-branch.xml:414
  1.8640 +msgid "Dealing with multiple named branches in a repository"
  1.8641 +msgstr ""
  1.8642 +
  1.8643 +#. type: Content of: <book><chapter><sect1><para>
  1.8644 +#: ../en/ch08-branch.xml:417
  1.8645 +msgid ""
  1.8646 +"If you have more than one named branch in a repository, Mercurial will "
  1.8647 +"remember the branch that your working directory on when you start a command "
  1.8648 +"like <command role=\"hg-cmd\">hg update</command> or <command role=\"hg-cmd"
  1.8649 +"\">hg pull -u</command>.  It will update the working directory to the tip of "
  1.8650 +"this branch, no matter what the <quote>repo-wide</quote> tip is.  To update "
  1.8651 +"to a revision that's on a different named branch, you may need to use the "
  1.8652 +"<option role=\"hg-opt-update\">-C</option> option to <command role=\"hg-cmd"
  1.8653 +"\">hg update</command>."
  1.8654 +msgstr ""
  1.8655 +
  1.8656 +#. type: Content of: <book><chapter><sect1><para>
  1.8657 +#: ../en/ch08-branch.xml:427
  1.8658 +msgid ""
  1.8659 +"This behaviour is a little subtle, so let's see it in action.  First, let's "
  1.8660 +"remind ourselves what branch we're currently on, and what branches are in our "
  1.8661 +"repository."
  1.8662 +msgstr ""
  1.8663 +
  1.8664 +#. type: Content of: <book><chapter><sect1><para>
  1.8665 +#: ../en/ch08-branch.xml:433
  1.8666 +msgid ""
  1.8667 +"We're on the <literal>bar</literal> branch, but there also exists an older "
  1.8668 +"<command role=\"hg-cmd\">hg foo</command> branch."
  1.8669 +msgstr ""
  1.8670 +
  1.8671 +#. type: Content of: <book><chapter><sect1><para>
  1.8672 +#: ../en/ch08-branch.xml:437
  1.8673 +msgid ""
  1.8674 +"We can <command role=\"hg-cmd\">hg update</command> back and forth between "
  1.8675 +"the tips of the <literal>foo</literal> and <literal>bar</literal> branches "
  1.8676 +"without needing to use the <option role=\"hg-opt-update\">-C</option> option, "
  1.8677 +"because this only involves going backwards and forwards linearly through our "
  1.8678 +"change history."
  1.8679 +msgstr ""
  1.8680 +
  1.8681 +#
  1.8682 +#. type: Content of: <book><chapter><sect1><para>
  1.8683 +#: ../en/ch08-branch.xml:446
  1.8684 +msgid ""
  1.8685 +"If we go back to the <literal>foo</literal> branch and then run <command role="
  1.8686 +"\"hg-cmd\">hg update</command>, it will keep us on <literal>foo</literal>, "
  1.8687 +"not move us to the tip of <literal>bar</literal>."
  1.8688 +msgstr ""
  1.8689 +
  1.8690 +#
  1.8691 +#. type: Content of: <book><chapter><sect1><para>
  1.8692 +#: ../en/ch08-branch.xml:453
  1.8693 +msgid ""
  1.8694 +"Committing a new change on the <literal>foo</literal> branch introduces a new "
  1.8695 +"head."
  1.8696 +msgstr ""
  1.8697 +
  1.8698 +#. type: Content of: <book><chapter><sect1><title>
  1.8699 +#: ../en/ch08-branch.xml:460
  1.8700 +msgid "Branch names and merging"
  1.8701 +msgstr ""
  1.8702 +
  1.8703 +#. type: Content of: <book><chapter><sect1><para>
  1.8704 +#: ../en/ch08-branch.xml:462
  1.8705 +msgid ""
  1.8706 +"As you've probably noticed, merges in Mercurial are not symmetrical. Let's "
  1.8707 +"say our repository has two heads, 17 and 23.  If I <command role=\"hg-cmd"
  1.8708 +"\">hg update</command> to 17 and then <command role=\"hg-cmd\">hg merge</"
  1.8709 +"command> with 23, Mercurial records 17 as the first parent of the merge, and "
  1.8710 +"23 as the second.  Whereas if I <command role=\"hg-cmd\">hg update</command> "
  1.8711 +"to 23 and then <command role=\"hg-cmd\">hg merge</command> with 17, it "
  1.8712 +"records 23 as the first parent, and 17 as the second."
  1.8713 +msgstr ""
  1.8714 +
  1.8715 +#. type: Content of: <book><chapter><sect1><para>
  1.8716 +#: ../en/ch08-branch.xml:472
  1.8717 +msgid ""
  1.8718 +"This affects Mercurial's choice of branch name when you merge.  After a "
  1.8719 +"merge, Mercurial will retain the branch name of the first parent when you "
  1.8720 +"commit the result of the merge.  If your first parent's branch name is "
  1.8721 +"<literal>foo</literal>, and you merge with <literal>bar</literal>, the branch "
  1.8722 +"name will still be <literal>foo</literal> after you merge."
  1.8723 +msgstr ""
  1.8724 +
  1.8725 +#. type: Content of: <book><chapter><sect1><para>
  1.8726 +#: ../en/ch08-branch.xml:479
  1.8727 +msgid ""
  1.8728 +"It's not unusual for a repository to contain multiple heads, each with the "
  1.8729 +"same branch name.  Let's say I'm working on the <literal>foo</literal> "
  1.8730 +"branch, and so are you.  We commit different changes; I pull your changes; I "
  1.8731 +"now have two heads, each claiming to be on the <literal>foo</literal> "
  1.8732 +"branch.  The result of a merge will be a single head on the <literal>foo</"
  1.8733 +"literal> branch, as you might hope."
  1.8734 +msgstr ""
  1.8735 +
  1.8736 +#
  1.8737 +#. type: Content of: <book><chapter><sect1><para>
  1.8738 +#: ../en/ch08-branch.xml:487
  1.8739 +msgid ""
  1.8740 +"But if I'm working on the <literal>bar</literal> branch, and I merge work "
  1.8741 +"from the <literal>foo</literal> branch, the result will remain on the "
  1.8742 +"<literal>bar</literal> branch."
  1.8743 +msgstr ""
  1.8744 +
  1.8745 +#. type: Content of: <book><chapter><sect1><para>
  1.8746 +#: ../en/ch08-branch.xml:493
  1.8747 +msgid ""
  1.8748 +"To give a more concrete example, if I'm working on the <literal>bleeding-"
  1.8749 +"edge</literal> branch, and I want to bring in the latest fixes from the "
  1.8750 +"<literal>stable</literal> branch, Mercurial will choose the <quote>right</"
  1.8751 +"quote> (<literal>bleeding-edge</literal>) branch name when I pull and merge "
  1.8752 +"from <literal>stable</literal>."
  1.8753 +msgstr ""
  1.8754 +
  1.8755 +#. type: Content of: <book><chapter><sect1><title>
  1.8756 +#: ../en/ch08-branch.xml:502
  1.8757 +msgid "Branch naming is generally useful"
  1.8758 +msgstr ""
  1.8759 +
  1.8760 +#. type: Content of: <book><chapter><sect1><para>
  1.8761 +#: ../en/ch08-branch.xml:504
  1.8762 +msgid ""
  1.8763 +"You shouldn't think of named branches as applicable only to situations where "
  1.8764 +"you have multiple long-lived branches cohabiting in a single repository.  "
  1.8765 +"They're very useful even in the one-branch-per-repository case."
  1.8766 +msgstr ""
  1.8767 +
  1.8768 +#. type: Content of: <book><chapter><sect1><para>
  1.8769 +#: ../en/ch08-branch.xml:509
  1.8770 +msgid ""
  1.8771 +"In the simplest case, giving a name to each branch gives you a permanent "
  1.8772 +"record of which branch a changeset originated on.  This gives you more "
  1.8773 +"context when you're trying to follow the history of a long-lived branchy "
  1.8774 +"project."
  1.8775 +msgstr ""
  1.8776 +
  1.8777 +#. type: Content of: <book><chapter><sect1><para>
  1.8778 +#: ../en/ch08-branch.xml:514
  1.8779 +msgid ""
  1.8780 +"If you're working with shared repositories, you can set up a <literal role="
  1.8781 +"\"hook\">pretxnchangegroup</literal> hook on each that will block incoming "
  1.8782 +"changes that have the <quote>wrong</quote> branch name.  This provides a "
  1.8783 +"simple, but effective, defence against people accidentally pushing changes "
  1.8784 +"from a <quote>bleeding edge</quote> branch to a <quote>stable</quote> "
  1.8785 +"branch.  Such a hook might look like this inside the shared repo's <filename "
  1.8786 +"role=\"special\"> /.hgrc</filename>."
  1.8787 +msgstr ""
  1.8788 +
  1.8789 +#. type: Content of: <book><chapter><title>
  1.8790 +#: ../en/ch09-undo.xml:5
  1.8791 +msgid "Finding and fixing mistakes"
  1.8792 +msgstr "查找和修改错误"
  1.8793 +
  1.8794 +#. type: Content of: <book><chapter><para>
  1.8795 +#: ../en/ch09-undo.xml:7
  1.8796 +msgid ""
  1.8797 +"To err might be human, but to really handle the consequences well takes a top-"
  1.8798 +"notch revision control system.  In this chapter, we'll discuss some of the "
  1.8799 +"techniques you can use when you find that a problem has crept into your "
  1.8800 +"project.  Mercurial has some highly capable features that will help you to "
  1.8801 +"isolate the sources of problems, and to handle them appropriately."
  1.8802 +msgstr ""
  1.8803 +
  1.8804 +#. type: Content of: <book><chapter><sect1><title>
  1.8805 +#: ../en/ch09-undo.xml:15
  1.8806 +msgid "Erasing local history"
  1.8807 +msgstr ""
  1.8808 +
  1.8809 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8810 +#: ../en/ch09-undo.xml:18
  1.8811 +msgid "The accidental commit"
  1.8812 +msgstr ""
  1.8813 +
  1.8814 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8815 +#: ../en/ch09-undo.xml:20
  1.8816 +msgid ""
  1.8817 +"I have the occasional but persistent problem of typing rather more quickly "
  1.8818 +"than I can think, which sometimes results in me committing a changeset that "
  1.8819 +"is either incomplete or plain wrong.  In my case, the usual kind of "
  1.8820 +"incomplete changeset is one in which I've created a new source file, but "
  1.8821 +"forgotten to <command role=\"hg-cmd\">hg add</command> it.  A <quote>plain "
  1.8822 +"wrong</quote> changeset is not as common, but no less annoying."
  1.8823 +msgstr ""
  1.8824 +
  1.8825 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8826 +#: ../en/ch09-undo.xml:31
  1.8827 +msgid "Rolling back a transaction"
  1.8828 +msgstr ""
  1.8829 +
  1.8830 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8831 +#: ../en/ch09-undo.xml:33
  1.8832 +msgid ""
  1.8833 +"In section <xref linkend=\"sec.concepts.txn\"/>, I mentioned that Mercurial "
  1.8834 +"treats each modification of a repository as a <emphasis>transaction</"
  1.8835 +"emphasis>.  Every time you commit a changeset or pull changes from another "
  1.8836 +"repository, Mercurial remembers what you did.  You can undo, or "
  1.8837 +"<emphasis>roll back</emphasis>, exactly one of these actions using the "
  1.8838 +"<command role=\"hg-cmd\">hg rollback</command> command.  (See section <xref "
  1.8839 +"linkend=\"sec.undo.rollback-after-push\"/> for an important caveat about the "
  1.8840 +"use of this command.)"
  1.8841 +msgstr ""
  1.8842 +
  1.8843 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8844 +#: ../en/ch09-undo.xml:43
  1.8845 +msgid ""
  1.8846 +"Here's a mistake that I often find myself making: committing a change in "
  1.8847 +"which I've created a new file, but forgotten to <command role=\"hg-cmd\">hg "
  1.8848 +"add</command> it."
  1.8849 +msgstr ""
  1.8850 +
  1.8851 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8852 +#: ../en/ch09-undo.xml:50
  1.8853 +msgid ""
  1.8854 +"Looking at the output of <command role=\"hg-cmd\">hg status</command> after "
  1.8855 +"the commit immediately confirms the error."
  1.8856 +msgstr ""
  1.8857 +
  1.8858 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8859 +#: ../en/ch09-undo.xml:56
  1.8860 +msgid ""
  1.8861 +"The commit captured the changes to the file <filename>a</filename>, but not "
  1.8862 +"the new file <filename>b</filename>.  If I were to push this changeset to a "
  1.8863 +"repository that I shared with a colleague, the chances are high that "
  1.8864 +"something in <filename>a</filename> would refer to <filename>b</filename>, "
  1.8865 +"which would not be present in their repository when they pulled my changes.  "
  1.8866 +"I would thus become the object of some indignation."
  1.8867 +msgstr ""
  1.8868 +
  1.8869 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8870 +#: ../en/ch09-undo.xml:65
  1.8871 +msgid ""
  1.8872 +"However, luck is with me&emdash;I've caught my error before I pushed the "
  1.8873 +"changeset.  I use the <command role=\"hg-cmd\">hg rollback</command> command, "
  1.8874 +"and Mercurial makes that last changeset vanish."
  1.8875 +msgstr ""
  1.8876 +
  1.8877 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8878 +#: ../en/ch09-undo.xml:72
  1.8879 +msgid ""
  1.8880 +"Notice that the changeset is no longer present in the repository's history, "
  1.8881 +"and the working directory once again thinks that the file <filename>a</"
  1.8882 +"filename> is modified.  The commit and rollback have left the working "
  1.8883 +"directory exactly as it was prior to the commit; the changeset has been "
  1.8884 +"completely erased.  I can now safely <command role=\"hg-cmd\">hg add</"
  1.8885 +"command> the file <filename>b</filename>, and rerun my commit."
  1.8886 +msgstr ""
  1.8887 +
  1.8888 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8889 +#: ../en/ch09-undo.xml:85
  1.8890 +msgid "The erroneous pull"
  1.8891 +msgstr ""
  1.8892 +
  1.8893 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8894 +#: ../en/ch09-undo.xml:87
  1.8895 +msgid ""
  1.8896 +"It's common practice with Mercurial to maintain separate development branches "
  1.8897 +"of a project in different repositories.  Your development team might have one "
  1.8898 +"shared repository for your project's <quote>0.9</quote> release, and another, "
  1.8899 +"containing different changes, for the <quote>1.0</quote> release."
  1.8900 +msgstr ""
  1.8901 +
  1.8902 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8903 +#: ../en/ch09-undo.xml:94
  1.8904 +msgid ""
  1.8905 +"Given this, you can imagine that the consequences could be messy if you had a "
  1.8906 +"local <quote>0.9</quote> repository, and accidentally pulled changes from the "
  1.8907 +"shared <quote>1.0</quote> repository into it.  At worst, you could be paying "
  1.8908 +"insufficient attention, and push those changes into the shared <quote>0.9</"
  1.8909 +"quote> tree, confusing your entire team (but don't worry, we'll return to "
  1.8910 +"this horror scenario later).  However, it's more likely that you'll notice "
  1.8911 +"immediately, because Mercurial will display the URL it's pulling from, or you "
  1.8912 +"will see it pull a suspiciously large number of changes into the repository."
  1.8913 +msgstr ""
  1.8914 +
  1.8915 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8916 +#: ../en/ch09-undo.xml:106
  1.8917 +msgid ""
  1.8918 +"The <command role=\"hg-cmd\">hg rollback</command> command will work nicely "
  1.8919 +"to expunge all of the changesets that you just pulled.  Mercurial groups all "
  1.8920 +"changes from one <command role=\"hg-cmd\">hg pull</command> into a single "
  1.8921 +"transaction, so one <command role=\"hg-cmd\">hg rollback</command> is all you "
  1.8922 +"need to undo this mistake."
  1.8923 +msgstr ""
  1.8924 +
  1.8925 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8926 +#: ../en/ch09-undo.xml:115
  1.8927 +msgid "Rolling back is useless once you've pushed"
  1.8928 +msgstr ""
  1.8929 +
  1.8930 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8931 +#: ../en/ch09-undo.xml:117
  1.8932 +msgid ""
  1.8933 +"The value of the <command role=\"hg-cmd\">hg rollback</command> command drops "
  1.8934 +"to zero once you've pushed your changes to another repository.  Rolling back "
  1.8935 +"a change makes it disappear entirely, but <emphasis>only</emphasis> in the "
  1.8936 +"repository in which you perform the <command role=\"hg-cmd\">hg rollback</"
  1.8937 +"command>.  Because a rollback eliminates history, there's no way for the "
  1.8938 +"disappearance of a change to propagate between repositories."
  1.8939 +msgstr ""
  1.8940 +
  1.8941 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8942 +#: ../en/ch09-undo.xml:126
  1.8943 +msgid ""
  1.8944 +"If you've pushed a change to another repository&emdash;particularly if it's a "
  1.8945 +"shared repository&emdash;it has essentially <quote>escaped into the wild,</"
  1.8946 +"quote> and you'll have to recover from your mistake in a different way.  What "
  1.8947 +"will happen if you push a changeset somewhere, then roll it back, then pull "
  1.8948 +"from the repository you pushed to, is that the changeset will reappear in "
  1.8949 +"your repository."
  1.8950 +msgstr ""
  1.8951 +
  1.8952 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8953 +#: ../en/ch09-undo.xml:135
  1.8954 +msgid ""
  1.8955 +"(If you absolutely know for sure that the change you want to roll back is the "
  1.8956 +"most recent change in the repository that you pushed to, <emphasis>and</"
  1.8957 +"emphasis> you know that nobody else could have pulled it from that "
  1.8958 +"repository, you can roll back the changeset there, too, but you really should "
  1.8959 +"really not rely on this working reliably.  If you do this, sooner or later a "
  1.8960 +"change really will make it into a repository that you don't directly control "
  1.8961 +"(or have forgotten about), and come back to bite you.)"
  1.8962 +msgstr ""
  1.8963 +
  1.8964 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.8965 +#: ../en/ch09-undo.xml:147
  1.8966 +msgid "You can only roll back once"
  1.8967 +msgstr ""
  1.8968 +
  1.8969 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8970 +#: ../en/ch09-undo.xml:149
  1.8971 +msgid ""
  1.8972 +"Mercurial stores exactly one transaction in its transaction log; that "
  1.8973 +"transaction is the most recent one that occurred in the repository. This "
  1.8974 +"means that you can only roll back one transaction.  If you expect to be able "
  1.8975 +"to roll back one transaction, then its predecessor, this is not the behaviour "
  1.8976 +"you will get."
  1.8977 +msgstr ""
  1.8978 +
  1.8979 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.8980 +#: ../en/ch09-undo.xml:158
  1.8981 +msgid ""
  1.8982 +"Once you've rolled back one transaction in a repository, you can't roll back "
  1.8983 +"again in that repository until you perform another commit or pull."
  1.8984 +msgstr ""
  1.8985 +
  1.8986 +#. type: Content of: <book><chapter><sect1><title>
  1.8987 +#: ../en/ch09-undo.xml:165
  1.8988 +msgid "Reverting the mistaken change"
  1.8989 +msgstr ""
  1.8990 +
  1.8991 +#. type: Content of: <book><chapter><sect1><para>
  1.8992 +#: ../en/ch09-undo.xml:167
  1.8993 +msgid ""
  1.8994 +"If you make a modification to a file, and decide that you really didn't want "
  1.8995 +"to change the file at all, and you haven't yet committed your changes, the "
  1.8996 +"<command role=\"hg-cmd\">hg revert</command> command is the one you'll need.  "
  1.8997 +"It looks at the changeset that's the parent of the working directory, and "
  1.8998 +"restores the contents of the file to their state as of that changeset. "
  1.8999 +"(That's a long-winded way of saying that, in the normal case, it undoes your "
  1.9000 +"modifications.)"
  1.9001 +msgstr ""
  1.9002 +
  1.9003 +#. type: Content of: <book><chapter><sect1><para>
  1.9004 +#: ../en/ch09-undo.xml:176
  1.9005 +msgid ""
  1.9006 +"Let's illustrate how the <command role=\"hg-cmd\">hg revert</command> command "
  1.9007 +"works with yet another small example.  We'll begin by modifying a file that "
  1.9008 +"Mercurial is already tracking."
  1.9009 +msgstr ""
  1.9010 +
  1.9011 +#. type: Content of: <book><chapter><sect1><para>
  1.9012 +#: ../en/ch09-undo.xml:183
  1.9013 +msgid ""
  1.9014 +"If we don't want that change, we can simply <command role=\"hg-cmd\">hg "
  1.9015 +"revert</command> the file."
  1.9016 +msgstr ""
  1.9017 +
  1.9018 +#. type: Content of: <book><chapter><sect1><para>
  1.9019 +#: ../en/ch09-undo.xml:189
  1.9020 +msgid ""
  1.9021 +"The <command role=\"hg-cmd\">hg revert</command> command provides us with an "
  1.9022 +"extra degree of safety by saving our modified file with a <filename>.orig</"
  1.9023 +"filename> extension."
  1.9024 +msgstr ""
  1.9025 +
  1.9026 +#. type: Content of: <book><chapter><sect1><para>
  1.9027 +#: ../en/ch09-undo.xml:196
  1.9028 +msgid ""
  1.9029 +"Here is a summary of the cases that the <command role=\"hg-cmd\">hg revert</"
  1.9030 +"command> command can deal with.  We will describe each of these in more "
  1.9031 +"detail in the section that follows."
  1.9032 +msgstr ""
  1.9033 +
  1.9034 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9035 +#: ../en/ch09-undo.xml:201
  1.9036 +msgid "If you modify a file, it will restore the file to its unmodified state."
  1.9037 +msgstr ""
  1.9038 +
  1.9039 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9040 +#: ../en/ch09-undo.xml:204
  1.9041 +msgid ""
  1.9042 +"If you <command role=\"hg-cmd\">hg add</command> a file, it will undo the "
  1.9043 +"<quote>added</quote> state of the file, but leave the file itself untouched."
  1.9044 +msgstr ""
  1.9045 +
  1.9046 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9047 +#: ../en/ch09-undo.xml:208
  1.9048 +msgid ""
  1.9049 +"If you delete a file without telling Mercurial, it will restore the file to "
  1.9050 +"its unmodified contents."
  1.9051 +msgstr ""
  1.9052 +
  1.9053 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9054 +#: ../en/ch09-undo.xml:211
  1.9055 +msgid ""
  1.9056 +"If you use the <command role=\"hg-cmd\">hg remove</command> command to remove "
  1.9057 +"a file, it will undo the <quote>removed</quote> state of the file, and "
  1.9058 +"restore the file to its unmodified contents."
  1.9059 +msgstr ""
  1.9060 +
  1.9061 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9062 +#: ../en/ch09-undo.xml:218
  1.9063 +msgid "File management errors"
  1.9064 +msgstr ""
  1.9065 +
  1.9066 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9067 +#: ../en/ch09-undo.xml:220
  1.9068 +msgid ""
  1.9069 +"The <command role=\"hg-cmd\">hg revert</command> command is useful for more "
  1.9070 +"than just modified files.  It lets you reverse the results of all of "
  1.9071 +"Mercurial's file management commands&emdash;<command role=\"hg-cmd\">hg add</"
  1.9072 +"command>, <command role=\"hg-cmd\">hg remove</command>, and so on."
  1.9073 +msgstr ""
  1.9074 +
  1.9075 +#
  1.9076 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9077 +#: ../en/ch09-undo.xml:226
  1.9078 +msgid ""
  1.9079 +"If you <command role=\"hg-cmd\">hg add</command> a file, then decide that in "
  1.9080 +"fact you don't want Mercurial to track it, use <command role=\"hg-cmd\">hg "
  1.9081 +"revert</command> to undo the add.  Don't worry; Mercurial will not modify the "
  1.9082 +"file in any way.  It will just <quote>unmark</quote> the file."
  1.9083 +msgstr ""
  1.9084 +
  1.9085 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9086 +#: ../en/ch09-undo.xml:234
  1.9087 +msgid ""
  1.9088 +"Similarly, if you ask Mercurial to <command role=\"hg-cmd\">hg remove</"
  1.9089 +"command> a file, you can use <command role=\"hg-cmd\">hg revert</command> to "
  1.9090 +"restore it to the contents it had as of the parent of the working directory.  "
  1.9091 +"&interaction.daily.revert.remove; This works just as well for a file that you "
  1.9092 +"deleted by hand, without telling Mercurial (recall that in Mercurial "
  1.9093 +"terminology, this kind of file is called <quote>missing</quote>)."
  1.9094 +msgstr ""
  1.9095 +
  1.9096 +#
  1.9097 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9098 +#: ../en/ch09-undo.xml:245
  1.9099 +msgid ""
  1.9100 +"If you revert a <command role=\"hg-cmd\">hg copy</command>, the copied-to "
  1.9101 +"file remains in your working directory afterwards, untracked.  Since a copy "
  1.9102 +"doesn't affect the copied-from file in any way, Mercurial doesn't do anything "
  1.9103 +"with the copied-from file."
  1.9104 +msgstr ""
  1.9105 +
  1.9106 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.9107 +#: ../en/ch09-undo.xml:254
  1.9108 +msgid "A slightly special case: reverting a rename"
  1.9109 +msgstr ""
  1.9110 +
  1.9111 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.9112 +#: ../en/ch09-undo.xml:256
  1.9113 +msgid ""
  1.9114 +"If you <command role=\"hg-cmd\">hg rename</command> a file, there is one "
  1.9115 +"small detail that you should remember.  When you <command role=\"hg-cmd\">hg "
  1.9116 +"revert</command> a rename, it's not enough to provide the name of the renamed-"
  1.9117 +"to file, as you can see here."
  1.9118 +msgstr ""
  1.9119 +
  1.9120 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.9121 +#: ../en/ch09-undo.xml:264
  1.9122 +msgid ""
  1.9123 +"As you can see from the output of <command role=\"hg-cmd\">hg status</"
  1.9124 +"command>, the renamed-to file is no longer identified as added, but the "
  1.9125 +"renamed-<emphasis>from</emphasis> file is still removed! This is counter-"
  1.9126 +"intuitive (at least to me), but at least it's easy to deal with."
  1.9127 +msgstr ""
  1.9128 +
  1.9129 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.9130 +#: ../en/ch09-undo.xml:273
  1.9131 +msgid ""
  1.9132 +"So remember, to revert a <command role=\"hg-cmd\">hg rename</command>, you "
  1.9133 +"must provide <emphasis>both</emphasis> the source and destination names."
  1.9134 +msgstr ""
  1.9135 +
  1.9136 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.9137 +#: ../en/ch09-undo.xml:278
  1.9138 +msgid "% TODO: the output doesn't look like it will be removed!"
  1.9139 +msgstr ""
  1.9140 +
  1.9141 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.9142 +#: ../en/ch09-undo.xml:281
  1.9143 +msgid ""
  1.9144 +"(By the way, if you rename a file, then modify the renamed-to file, then "
  1.9145 +"revert both components of the rename, when Mercurial restores the file that "
  1.9146 +"was removed as part of the rename, it will be unmodified. If you need the "
  1.9147 +"modifications in the renamed-to file to show up in the renamed-from file, "
  1.9148 +"don't forget to copy them over.)"
  1.9149 +msgstr ""
  1.9150 +
  1.9151 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.9152 +#: ../en/ch09-undo.xml:288
  1.9153 +msgid ""
  1.9154 +"These fiddly aspects of reverting a rename arguably constitute a small bug in "
  1.9155 +"Mercurial."
  1.9156 +msgstr ""
  1.9157 +
  1.9158 +#. type: Content of: <book><chapter><sect1><title>
  1.9159 +#: ../en/ch09-undo.xml:295
  1.9160 +msgid "Dealing with committed changes"
  1.9161 +msgstr ""
  1.9162 +
  1.9163 +#. type: Content of: <book><chapter><sect1><para>
  1.9164 +#: ../en/ch09-undo.xml:297
  1.9165 +msgid ""
  1.9166 +"Consider a case where you have committed a change $a$, and another change $b$ "
  1.9167 +"on top of it; you then realise that change $a$ was incorrect.  Mercurial lets "
  1.9168 +"you <quote>back out</quote> an entire changeset automatically, and building "
  1.9169 +"blocks that let you reverse part of a changeset by hand."
  1.9170 +msgstr ""
  1.9171 +
  1.9172 +#. type: Content of: <book><chapter><sect1><para>
  1.9173 +#: ../en/ch09-undo.xml:303
  1.9174 +msgid ""
  1.9175 +"Before you read this section, here's something to keep in mind: the <command "
  1.9176 +"role=\"hg-cmd\">hg backout</command> command undoes changes by "
  1.9177 +"<emphasis>adding</emphasis> history, not by modifying or erasing it.  It's "
  1.9178 +"the right tool to use if you're fixing bugs, but not if you're trying to undo "
  1.9179 +"some change that has catastrophic consequences.  To deal with those, see "
  1.9180 +"section <xref linkend=\"sec.undo.aaaiiieee\"/>."
  1.9181 +msgstr ""
  1.9182 +
  1.9183 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9184 +#: ../en/ch09-undo.xml:312
  1.9185 +msgid "Backing out a changeset"
  1.9186 +msgstr ""
  1.9187 +
  1.9188 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9189 +#: ../en/ch09-undo.xml:314
  1.9190 +msgid ""
  1.9191 +"The <command role=\"hg-cmd\">hg backout</command> command lets you "
  1.9192 +"<quote>undo</quote> the effects of an entire changeset in an automated "
  1.9193 +"fashion.  Because Mercurial's history is immutable, this command "
  1.9194 +"<emphasis>does not</emphasis> get rid of the changeset you want to undo.  "
  1.9195 +"Instead, it creates a new changeset that <emphasis>reverses</emphasis> the "
  1.9196 +"effect of the to-be-undone changeset."
  1.9197 +msgstr ""
  1.9198 +
  1.9199 +#
  1.9200 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9201 +#: ../en/ch09-undo.xml:323
  1.9202 +msgid ""
  1.9203 +"The operation of the <command role=\"hg-cmd\">hg backout</command> command is "
  1.9204 +"a little intricate, so let's illustrate it with some examples.  First, we'll "
  1.9205 +"create a repository with some simple changes."
  1.9206 +msgstr ""
  1.9207 +
  1.9208 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9209 +#: ../en/ch09-undo.xml:330
  1.9210 +msgid ""
  1.9211 +"The <command role=\"hg-cmd\">hg backout</command> command takes a single "
  1.9212 +"changeset ID as its argument; this is the changeset to back out.  Normally, "
  1.9213 +"<command role=\"hg-cmd\">hg backout</command> will drop you into a text "
  1.9214 +"editor to write a commit message, so you can record why you're backing the "
  1.9215 +"change out.  In this example, we provide a commit message on the command line "
  1.9216 +"using the <option role=\"hg-opt-backout\">-m</option> option."
  1.9217 +msgstr ""
  1.9218 +
  1.9219 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9220 +#: ../en/ch09-undo.xml:341
  1.9221 +msgid "Backing out the tip changeset"
  1.9222 +msgstr ""
  1.9223 +
  1.9224 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9225 +#: ../en/ch09-undo.xml:343
  1.9226 +msgid "We're going to start by backing out the last changeset we committed."
  1.9227 +msgstr ""
  1.9228 +
  1.9229 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9230 +#: ../en/ch09-undo.xml:348
  1.9231 +msgid ""
  1.9232 +"You can see that the second line from <filename>myfile</filename> is no "
  1.9233 +"longer present.  Taking a look at the output of <command role=\"hg-cmd\">hg "
  1.9234 +"log</command> gives us an idea of what the <command role=\"hg-cmd\">hg "
  1.9235 +"backout</command> command has done.  &interaction.backout.simple.log; Notice "
  1.9236 +"that the new changeset that <command role=\"hg-cmd\">hg backout</command> has "
  1.9237 +"created is a child of the changeset we backed out.  It's easier to see this "
  1.9238 +"in figure <xref linkend=\"fig.undo.backout\"/>, which presents a graphical "
  1.9239 +"view of the change history.  As you can see, the history is nice and linear."
  1.9240 +msgstr ""
  1.9241 +
  1.9242 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.9243 +#: ../en/ch09-undo.xml:362
  1.9244 +msgid ""
  1.9245 +"<imageobject><imagedata fileref=\"images/undo-simple.png\"/></imageobject>"
  1.9246 +msgstr ""
  1.9247 +
  1.9248 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.9249 +#: ../en/ch09-undo.xml:364 ../en/ch09-undo.xml:477
  1.9250 +msgid ""
  1.9251 +"Backing out a change using the <command role=\"hg-cmd\">hg backout</command> "
  1.9252 +"command"
  1.9253 +msgstr ""
  1.9254 +
  1.9255 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9256 +#: ../en/ch09-undo.xml:373
  1.9257 +msgid "Backing out a non-tip change"
  1.9258 +msgstr ""
  1.9259 +
  1.9260 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9261 +#: ../en/ch09-undo.xml:375
  1.9262 +msgid ""
  1.9263 +"If you want to back out a change other than the last one you committed, pass "
  1.9264 +"the <option role=\"hg-opt-backout\">--merge</option> option to the <command "
  1.9265 +"role=\"hg-cmd\">hg backout</command> command."
  1.9266 +msgstr ""
  1.9267 +
  1.9268 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9269 +#: ../en/ch09-undo.xml:382
  1.9270 +msgid ""
  1.9271 +"This makes backing out any changeset a <quote>one-shot</quote> operation "
  1.9272 +"that's usually simple and fast."
  1.9273 +msgstr ""
  1.9274 +
  1.9275 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9276 +#: ../en/ch09-undo.xml:388
  1.9277 +msgid ""
  1.9278 +"If you take a look at the contents of <filename>myfile</filename> after the "
  1.9279 +"backout finishes, you'll see that the first and third changes are present, "
  1.9280 +"but not the second."
  1.9281 +msgstr ""
  1.9282 +
  1.9283 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9284 +#: ../en/ch09-undo.xml:395
  1.9285 +msgid ""
  1.9286 +"As the graphical history in figure <xref linkend=\"fig.undo.backout-non-tip\"/"
  1.9287 +"> illustrates, Mercurial actually commits <emphasis>two</emphasis> changes in "
  1.9288 +"this kind of situation (the box-shaped nodes are the ones that Mercurial "
  1.9289 +"commits automatically).  Before Mercurial begins the backout process, it "
  1.9290 +"first remembers what the current parent of the working directory is.  It then "
  1.9291 +"backs out the target changeset, and commits that as a changeset.  Finally, it "
  1.9292 +"merges back to the previous parent of the working directory, and commits the "
  1.9293 +"result of the merge."
  1.9294 +msgstr ""
  1.9295 +
  1.9296 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9297 +#: ../en/ch09-undo.xml:406
  1.9298 +msgid ""
  1.9299 +"% TODO: to me it looks like mercurial doesn't commit the second merge "
  1.9300 +"automatically!"
  1.9301 +msgstr ""
  1.9302 +
  1.9303 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.9304 +#: ../en/ch09-undo.xml:410
  1.9305 +msgid ""
  1.9306 +"<imageobject><imagedata fileref=\"images/undo-non-tip.png\"/></imageobject>"
  1.9307 +msgstr ""
  1.9308 +
  1.9309 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.9310 +#: ../en/ch09-undo.xml:412
  1.9311 +msgid ""
  1.9312 +"Automated backout of a non-tip change using the <command role=\"hg-cmd\">hg "
  1.9313 +"backout</command> command"
  1.9314 +msgstr ""
  1.9315 +
  1.9316 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9317 +#: ../en/ch09-undo.xml:418
  1.9318 +msgid ""
  1.9319 +"The result is that you end up <quote>back where you were</quote>, only with "
  1.9320 +"some extra history that undoes the effect of the changeset you wanted to back "
  1.9321 +"out."
  1.9322 +msgstr ""
  1.9323 +
  1.9324 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
  1.9325 +#: ../en/ch09-undo.xml:423
  1.9326 +msgid "Always use the <option role=\"hg-opt-backout\">--merge</option> option"
  1.9327 +msgstr ""
  1.9328 +
  1.9329 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
  1.9330 +#: ../en/ch09-undo.xml:426
  1.9331 +msgid ""
  1.9332 +"In fact, since the <option role=\"hg-opt-backout\">--merge</option> option "
  1.9333 +"will do the <quote>right thing</quote> whether or not the changeset you're "
  1.9334 +"backing out is the tip (i.e. it won't try to merge if it's backing out the "
  1.9335 +"tip, since there's no need), you should <emphasis>always</emphasis> use this "
  1.9336 +"option when you run the <command role=\"hg-cmd\">hg backout</command> command."
  1.9337 +msgstr ""
  1.9338 +
  1.9339 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9340 +#: ../en/ch09-undo.xml:437
  1.9341 +msgid "Gaining more control of the backout process"
  1.9342 +msgstr ""
  1.9343 +
  1.9344 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9345 +#: ../en/ch09-undo.xml:439
  1.9346 +msgid ""
  1.9347 +"While I've recommended that you always use the <option role=\"hg-opt-backout"
  1.9348 +"\">--merge</option> option when backing out a change, the <command role=\"hg-"
  1.9349 +"cmd\">hg backout</command> command lets you decide how to merge a backout "
  1.9350 +"changeset.  Taking control of the backout process by hand is something you "
  1.9351 +"will rarely need to do, but it can be useful to understand what the <command "
  1.9352 +"role=\"hg-cmd\">hg backout</command> command is doing for you automatically.  "
  1.9353 +"To illustrate this, let's clone our first repository, but omit the backout "
  1.9354 +"change that it contains."
  1.9355 +msgstr ""
  1.9356 +
  1.9357 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9358 +#: ../en/ch09-undo.xml:452
  1.9359 +msgid ""
  1.9360 +"As with our earlier example, We'll commit a third changeset, then back out "
  1.9361 +"its parent, and see what happens."
  1.9362 +msgstr ""
  1.9363 +
  1.9364 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9365 +#: ../en/ch09-undo.xml:458
  1.9366 +msgid ""
  1.9367 +"Our new changeset is again a descendant of the changeset we backout out; it's "
  1.9368 +"thus a new head, <emphasis>not</emphasis> a descendant of the changeset that "
  1.9369 +"was the tip.  The <command role=\"hg-cmd\">hg backout</command> command was "
  1.9370 +"quite explicit in telling us this."
  1.9371 +msgstr ""
  1.9372 +
  1.9373 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9374 +#: ../en/ch09-undo.xml:466
  1.9375 +msgid ""
  1.9376 +"Again, it's easier to see what has happened by looking at a graph of the "
  1.9377 +"revision history, in figure <xref linkend=\"fig.undo.backout-manual\"/>.  "
  1.9378 +"This makes it clear that when we use <command role=\"hg-cmd\">hg backout</"
  1.9379 +"command> to back out a change other than the tip, Mercurial adds a new head "
  1.9380 +"to the repository (the change it committed is box-shaped)."
  1.9381 +msgstr ""
  1.9382 +
  1.9383 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.9384 +#: ../en/ch09-undo.xml:475
  1.9385 +msgid ""
  1.9386 +"<imageobject><imagedata fileref=\"images/undo-manual.png\"/></imageobject>"
  1.9387 +msgstr ""
  1.9388 +
  1.9389 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9390 +#: ../en/ch09-undo.xml:484
  1.9391 +msgid ""
  1.9392 +"After the <command role=\"hg-cmd\">hg backout</command> command has "
  1.9393 +"completed, it leaves the new <quote>backout</quote> changeset as the parent "
  1.9394 +"of the working directory."
  1.9395 +msgstr ""
  1.9396 +
  1.9397 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9398 +#: ../en/ch09-undo.xml:491
  1.9399 +msgid "Now we have two isolated sets of changes."
  1.9400 +msgstr ""
  1.9401 +
  1.9402 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9403 +#: ../en/ch09-undo.xml:495
  1.9404 +msgid ""
  1.9405 +"Let's think about what we expect to see as the contents of <filename>myfile</"
  1.9406 +"filename> now.  The first change should be present, because we've never "
  1.9407 +"backed it out.  The second change should be missing, as that's the change we "
  1.9408 +"backed out.  Since the history graph shows the third change as a separate "
  1.9409 +"head, we <emphasis>don't</emphasis> expect to see the third change present in "
  1.9410 +"<filename>myfile</filename>."
  1.9411 +msgstr ""
  1.9412 +
  1.9413 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9414 +#: ../en/ch09-undo.xml:505
  1.9415 +msgid ""
  1.9416 +"To get the third change back into the file, we just do a normal merge of our "
  1.9417 +"two heads."
  1.9418 +msgstr ""
  1.9419 +
  1.9420 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9421 +#: ../en/ch09-undo.xml:510
  1.9422 +msgid ""
  1.9423 +"Afterwards, the graphical history of our repository looks like figure <xref "
  1.9424 +"linkend=\"fig.undo.backout-manual-merge\"/>."
  1.9425 +msgstr ""
  1.9426 +
  1.9427 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
  1.9428 +#: ../en/ch09-undo.xml:515
  1.9429 +msgid ""
  1.9430 +"<imageobject><imagedata fileref=\"images/undo-manual-merge.png\"/></"
  1.9431 +"imageobject>"
  1.9432 +msgstr ""
  1.9433 +
  1.9434 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
  1.9435 +#: ../en/ch09-undo.xml:517
  1.9436 +msgid "Manually merging a backout change"
  1.9437 +msgstr ""
  1.9438 +
  1.9439 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9440 +#: ../en/ch09-undo.xml:524
  1.9441 +msgid "Why <command role=\"hg-cmd\">hg backout</command> works as it does"
  1.9442 +msgstr ""
  1.9443 +
  1.9444 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9445 +#: ../en/ch09-undo.xml:527
  1.9446 +msgid ""
  1.9447 +"Here's a brief description of how the <command role=\"hg-cmd\">hg backout</"
  1.9448 +"command> command works."
  1.9449 +msgstr ""
  1.9450 +
  1.9451 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9452 +#: ../en/ch09-undo.xml:530
  1.9453 +msgid ""
  1.9454 +"It ensures that the working directory is <quote>clean</quote>, i.e. that the "
  1.9455 +"output of <command role=\"hg-cmd\">hg status</command> would be empty."
  1.9456 +msgstr ""
  1.9457 +
  1.9458 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9459 +#: ../en/ch09-undo.xml:534
  1.9460 +msgid ""
  1.9461 +"It remembers the current parent of the working directory.  Let's call this "
  1.9462 +"changeset <literal>orig</literal>"
  1.9463 +msgstr ""
  1.9464 +
  1.9465 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9466 +#: ../en/ch09-undo.xml:538
  1.9467 +msgid ""
  1.9468 +"It does the equivalent of a <command role=\"hg-cmd\">hg update</command> to "
  1.9469 +"sync the working directory to the changeset you want to back out.  Let's call "
  1.9470 +"this changeset <literal>backout</literal>"
  1.9471 +msgstr ""
  1.9472 +
  1.9473 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9474 +#: ../en/ch09-undo.xml:543
  1.9475 +msgid ""
  1.9476 +"It finds the parent of that changeset.  Let's call that changeset "
  1.9477 +"<literal>parent</literal>."
  1.9478 +msgstr ""
  1.9479 +
  1.9480 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9481 +#: ../en/ch09-undo.xml:546
  1.9482 +msgid ""
  1.9483 +"For each file that the <literal>backout</literal> changeset affected, it does "
  1.9484 +"the equivalent of a <command role=\"hg-cmd\">hg revert -r parent</command> on "
  1.9485 +"that file, to restore it to the contents it had before that changeset was "
  1.9486 +"committed."
  1.9487 +msgstr ""
  1.9488 +
  1.9489 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9490 +#: ../en/ch09-undo.xml:553
  1.9491 +msgid ""
  1.9492 +"It commits the result as a new changeset.  This changeset has "
  1.9493 +"<literal>backout</literal> as its parent."
  1.9494 +msgstr ""
  1.9495 +
  1.9496 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9497 +#: ../en/ch09-undo.xml:557
  1.9498 +msgid ""
  1.9499 +"If you specify <option role=\"hg-opt-backout\">--merge</option> on the "
  1.9500 +"command line, it merges with <literal>orig</literal>, and commits the result "
  1.9501 +"of the merge."
  1.9502 +msgstr ""
  1.9503 +
  1.9504 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9505 +#: ../en/ch09-undo.xml:563
  1.9506 +msgid ""
  1.9507 +"An alternative way to implement the <command role=\"hg-cmd\">hg backout</"
  1.9508 +"command> command would be to <command role=\"hg-cmd\">hg export</command> the "
  1.9509 +"to-be-backed-out changeset as a diff, then use the <option role=\"cmd-opt-"
  1.9510 +"patch\">--reverse</option> option to the <command>patch</command> command to "
  1.9511 +"reverse the effect of the change without fiddling with the working "
  1.9512 +"directory.  This sounds much simpler, but it would not work nearly as well."
  1.9513 +msgstr ""
  1.9514 +
  1.9515 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9516 +#: ../en/ch09-undo.xml:573
  1.9517 +msgid ""
  1.9518 +"The reason that <command role=\"hg-cmd\">hg backout</command> does an update, "
  1.9519 +"a commit, a merge, and another commit is to give the merge machinery the best "
  1.9520 +"chance to do a good job when dealing with all the changes <emphasis>between</"
  1.9521 +"emphasis> the change you're backing out and the current tip."
  1.9522 +msgstr ""
  1.9523 +
  1.9524 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9525 +#: ../en/ch09-undo.xml:580
  1.9526 +msgid ""
  1.9527 +"If you're backing out a changeset that's 100 revisions back in your project's "
  1.9528 +"history, the chances that the <command>patch</command> command will be able "
  1.9529 +"to apply a reverse diff cleanly are not good, because intervening changes are "
  1.9530 +"likely to have <quote>broken the context</quote> that <command>patch</"
  1.9531 +"command> uses to determine whether it can apply a patch (if this sounds like "
  1.9532 +"gibberish, see <xref linkend=\"sec.mq.patch\"/> for a discussion of the "
  1.9533 +"<command>patch</command> command).  Also, Mercurial's merge machinery will "
  1.9534 +"handle files and directories being renamed, permission changes, and "
  1.9535 +"modifications to binary files, none of which <command>patch</command> can "
  1.9536 +"deal with."
  1.9537 +msgstr ""
  1.9538 +
  1.9539 +#. type: Content of: <book><chapter><sect1><title>
  1.9540 +#: ../en/ch09-undo.xml:597
  1.9541 +msgid "Changes that should never have been"
  1.9542 +msgstr ""
  1.9543 +
  1.9544 +#. type: Content of: <book><chapter><sect1><para>
  1.9545 +#: ../en/ch09-undo.xml:599
  1.9546 +msgid ""
  1.9547 +"Most of the time, the <command role=\"hg-cmd\">hg backout</command> command "
  1.9548 +"is exactly what you need if you want to undo the effects of a change.  It "
  1.9549 +"leaves a permanent record of exactly what you did, both when committing the "
  1.9550 +"original changeset and when you cleaned up after it."
  1.9551 +msgstr ""
  1.9552 +
  1.9553 +#. type: Content of: <book><chapter><sect1><para>
  1.9554 +#: ../en/ch09-undo.xml:605
  1.9555 +msgid ""
  1.9556 +"On rare occasions, though, you may find that you've committed a change that "
  1.9557 +"really should not be present in the repository at all.  For example, it would "
  1.9558 +"be very unusual, and usually considered a mistake, to commit a software "
  1.9559 +"project's object files as well as its source files.  Object files have almost "
  1.9560 +"no intrinsic value, and they're <emphasis>big</emphasis>, so they increase "
  1.9561 +"the size of the repository and the amount of time it takes to clone or pull "
  1.9562 +"changes."
  1.9563 +msgstr ""
  1.9564 +
  1.9565 +#. type: Content of: <book><chapter><sect1><para>
  1.9566 +#: ../en/ch09-undo.xml:614
  1.9567 +msgid ""
  1.9568 +"Before I discuss the options that you have if you commit a <quote>brown paper "
  1.9569 +"bag</quote> change (the kind that's so bad that you want to pull a brown "
  1.9570 +"paper bag over your head), let me first discuss some approaches that probably "
  1.9571 +"won't work."
  1.9572 +msgstr ""
  1.9573 +
  1.9574 +#. type: Content of: <book><chapter><sect1><para>
  1.9575 +#: ../en/ch09-undo.xml:619
  1.9576 +msgid ""
  1.9577 +"Since Mercurial treats history as accumulative&emdash;every change builds on "
  1.9578 +"top of all changes that preceded it&emdash;you generally can't just make "
  1.9579 +"disastrous changes disappear.  The one exception is when you've just "
  1.9580 +"committed a change, and it hasn't been pushed or pulled into another "
  1.9581 +"repository.  That's when you can safely use the <command role=\"hg-cmd\">hg "
  1.9582 +"rollback</command> command, as I detailed in section <xref linkend=\"sec.undo."
  1.9583 +"rollback\"/>."
  1.9584 +msgstr ""
  1.9585 +
  1.9586 +#. type: Content of: <book><chapter><sect1><para>
  1.9587 +#: ../en/ch09-undo.xml:628
  1.9588 +msgid ""
  1.9589 +"After you've pushed a bad change to another repository, you <emphasis>could</"
  1.9590 +"emphasis> still use <command role=\"hg-cmd\">hg rollback</command> to make "
  1.9591 +"your local copy of the change disappear, but it won't have the consequences "
  1.9592 +"you want.  The change will still be present in the remote repository, so it "
  1.9593 +"will reappear in your local repository the next time you pull."
  1.9594 +msgstr ""
  1.9595 +
  1.9596 +#. type: Content of: <book><chapter><sect1><para>
  1.9597 +#: ../en/ch09-undo.xml:636
  1.9598 +msgid ""
  1.9599 +"If a situation like this arises, and you know which repositories your bad "
  1.9600 +"change has propagated into, you can <emphasis>try</emphasis> to get rid of "
  1.9601 +"the changeefrom <emphasis>every</emphasis> one of those repositories.  This "
  1.9602 +"is, of course, not a satisfactory solution: if you miss even a single "
  1.9603 +"repository while you're expunging, the change is still <quote>in the wild</"
  1.9604 +"quote>, and could propagate further."
  1.9605 +msgstr ""
  1.9606 +
  1.9607 +#. type: Content of: <book><chapter><sect1><para>
  1.9608 +#: ../en/ch09-undo.xml:644
  1.9609 +msgid ""
  1.9610 +"If you've committed one or more changes <emphasis>after</emphasis> the change "
  1.9611 +"that you'd like to see disappear, your options are further reduced. Mercurial "
  1.9612 +"doesn't provide a way to <quote>punch a hole</quote> in history, leaving "
  1.9613 +"changesets intact."
  1.9614 +msgstr ""
  1.9615 +
  1.9616 +#. type: Content of: <book><chapter><sect1><para>
  1.9617 +#: ../en/ch09-undo.xml:650
  1.9618 +msgid ""
  1.9619 +"XXX This needs filling out.  The <literal>hg-replay</literal> script in the "
  1.9620 +"<literal>examples</literal> directory works, but doesn't handle merge "
  1.9621 +"changesets.  Kind of an important omission."
  1.9622 +msgstr ""
  1.9623 +
  1.9624 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9625 +#: ../en/ch09-undo.xml:656
  1.9626 +msgid "Protect yourself from <quote>escaped</quote> changes"
  1.9627 +msgstr ""
  1.9628 +
  1.9629 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9630 +#: ../en/ch09-undo.xml:659
  1.9631 +msgid ""
  1.9632 +"If you've committed some changes to your local repository and they've been "
  1.9633 +"pushed or pulled somewhere else, this isn't necessarily a disaster.  You can "
  1.9634 +"protect yourself ahead of time against some classes of bad changeset.  This "
  1.9635 +"is particularly easy if your team usually pulls changes from a central "
  1.9636 +"repository."
  1.9637 +msgstr ""
  1.9638 +
  1.9639 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9640 +#: ../en/ch09-undo.xml:666
  1.9641 +msgid ""
  1.9642 +"By configuring some hooks on that repository to validate incoming changesets "
  1.9643 +"(see chapter <xref linkend=\"chap.hook\"/>), you can automatically prevent "
  1.9644 +"some kinds of bad changeset from being pushed to the central repository at "
  1.9645 +"all.  With such a configuration in place, some kinds of bad changeset will "
  1.9646 +"naturally tend to <quote>die out</quote> because they can't propagate into "
  1.9647 +"the central repository.  Better yet, this happens without any need for "
  1.9648 +"explicit intervention."
  1.9649 +msgstr ""
  1.9650 +
  1.9651 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9652 +#: ../en/ch09-undo.xml:676
  1.9653 +msgid ""
  1.9654 +"For instance, an incoming change hook that verifies that a changeset will "
  1.9655 +"actually compile can prevent people from inadvertantly <quote>breaking the "
  1.9656 +"build</quote>."
  1.9657 +msgstr ""
  1.9658 +
  1.9659 +#. type: Content of: <book><chapter><sect1><title>
  1.9660 +#: ../en/ch09-undo.xml:683
  1.9661 +msgid "Finding the source of a bug"
  1.9662 +msgstr ""
  1.9663 +
  1.9664 +#. type: Content of: <book><chapter><sect1><para>
  1.9665 +#: ../en/ch09-undo.xml:685
  1.9666 +msgid ""
  1.9667 +"While it's all very well to be able to back out a changeset that introduced a "
  1.9668 +"bug, this requires that you know which changeset to back out.  Mercurial "
  1.9669 +"provides an invaluable command, called <command role=\"hg-cmd\">hg bisect</"
  1.9670 +"command>, that helps you to automate this process and accomplish it very "
  1.9671 +"efficiently."
  1.9672 +msgstr ""
  1.9673 +
  1.9674 +#. type: Content of: <book><chapter><sect1><para>
  1.9675 +#: ../en/ch09-undo.xml:692
  1.9676 +msgid ""
  1.9677 +"The idea behind the <command role=\"hg-cmd\">hg bisect</command> command is "
  1.9678 +"that a changeset has introduced some change of behaviour that you can "
  1.9679 +"identify with a simple binary test.  You don't know which piece of code "
  1.9680 +"introduced the change, but you know how to test for the presence of the bug.  "
  1.9681 +"The <command role=\"hg-cmd\">hg bisect</command> command uses your test to "
  1.9682 +"direct its search for the changeset that introduced the code that caused the "
  1.9683 +"bug."
  1.9684 +msgstr ""
  1.9685 +
  1.9686 +#. type: Content of: <book><chapter><sect1><para>
  1.9687 +#: ../en/ch09-undo.xml:701
  1.9688 +msgid ""
  1.9689 +"Here are a few scenarios to help you understand how you might apply this "
  1.9690 +"command."
  1.9691 +msgstr ""
  1.9692 +
  1.9693 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9694 +#: ../en/ch09-undo.xml:704
  1.9695 +msgid ""
  1.9696 +"The most recent version of your software has a bug that you remember wasn't "
  1.9697 +"present a few weeks ago, but you don't know when it was introduced.  Here, "
  1.9698 +"your binary test checks for the presence of that bug."
  1.9699 +msgstr ""
  1.9700 +
  1.9701 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9702 +#: ../en/ch09-undo.xml:709
  1.9703 +msgid ""
  1.9704 +"You fixed a bug in a rush, and now it's time to close the entry in your "
  1.9705 +"team's bug database.  The bug database requires a changeset ID when you close "
  1.9706 +"an entry, but you don't remember which changeset you fixed the bug in.  Once "
  1.9707 +"again, your binary test checks for the presence of the bug."
  1.9708 +msgstr ""
  1.9709 +
  1.9710 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9711 +#: ../en/ch09-undo.xml:716
  1.9712 +msgid ""
  1.9713 +"Your software works correctly, but runs 15% slower than the last time you "
  1.9714 +"measured it.  You want to know which changeset introduced the performance "
  1.9715 +"regression.  In this case, your binary test measures the performance of your "
  1.9716 +"software, to see whether it's <quote>fast</quote> or <quote>slow</quote>."
  1.9717 +msgstr ""
  1.9718 +
  1.9719 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
  1.9720 +#: ../en/ch09-undo.xml:723
  1.9721 +msgid ""
  1.9722 +"The sizes of the components of your project that you ship exploded recently, "
  1.9723 +"and you suspect that something changed in the way you build your project."
  1.9724 +msgstr ""
  1.9725 +
  1.9726 +#. type: Content of: <book><chapter><sect1><para>
  1.9727 +#: ../en/ch09-undo.xml:728
  1.9728 +msgid ""
  1.9729 +"From these examples, it should be clear that the <command role=\"hg-cmd\">hg "
  1.9730 +"bisect</command> command is not useful only for finding the sources of bugs.  "
  1.9731 +"You can use it to find any <quote>emergent property</quote> of a repository "
  1.9732 +"(anything that you can't find from a simple text search of the files in the "
  1.9733 +"tree) for which you can write a binary test."
  1.9734 +msgstr ""
  1.9735 +
  1.9736 +#. type: Content of: <book><chapter><sect1><para>
  1.9737 +#: ../en/ch09-undo.xml:735
  1.9738 +msgid ""
  1.9739 +"We'll introduce a little bit of terminology here, just to make it clear which "
  1.9740 +"parts of the search process are your responsibility, and which are "
  1.9741 +"Mercurial's.  A <emphasis>test</emphasis> is something that <emphasis>you</"
  1.9742 +"emphasis> run when <command role=\"hg-cmd\">hg bisect</command> chooses a "
  1.9743 +"changeset.  A <emphasis>probe</emphasis> is what <command role=\"hg-cmd\">hg "
  1.9744 +"bisect</command> runs to tell whether a revision is good.  Finally, we'll use "
  1.9745 +"the word <quote>bisect</quote>, as both a noun and a verb, to stand in for "
  1.9746 +"the phrase <quote>search using the <command role=\"hg-cmd\">hg bisect</"
  1.9747 +"command> command</quote>."
  1.9748 +msgstr ""
  1.9749 +
  1.9750 +#. type: Content of: <book><chapter><sect1><para>
  1.9751 +#: ../en/ch09-undo.xml:748
  1.9752 +msgid ""
  1.9753 +"One simple way to automate the searching process would be simply to probe "
  1.9754 +"every changeset.  However, this scales poorly.  If it took ten minutes to "
  1.9755 +"test a single changeset, and you had 10,000 changesets in your repository, "
  1.9756 +"the exhaustive approach would take on average 35 <emphasis>days</emphasis> to "
  1.9757 +"find the changeset that introduced a bug.  Even if you knew that the bug was "
  1.9758 +"introduced by one of the last 500 changesets, and limited your search to "
  1.9759 +"those, you'd still be looking at over 40 hours to find the changeset that "
  1.9760 +"introduced your bug."
  1.9761 +msgstr ""
  1.9762 +
  1.9763 +#. type: Content of: <book><chapter><sect1><para>
  1.9764 +#: ../en/ch09-undo.xml:758
  1.9765 +msgid ""
  1.9766 +"What the <command role=\"hg-cmd\">hg bisect</command> command does is use its "
  1.9767 +"knowledge of the <quote>shape</quote> of your project's revision history to "
  1.9768 +"perform a search in time proportional to the <emphasis>logarithm</emphasis> "
  1.9769 +"of the number of changesets to check (the kind of search it performs is "
  1.9770 +"called a dichotomic search).  With this approach, searching through 10,000 "
  1.9771 +"changesets will take less than three hours, even at ten minutes per test (the "
  1.9772 +"search will require about 14 tests).  Limit your search to the last hundred "
  1.9773 +"changesets, and it will take only about an hour (roughly seven tests)."
  1.9774 +msgstr ""
  1.9775 +
  1.9776 +#. type: Content of: <book><chapter><sect1><para>
  1.9777 +#: ../en/ch09-undo.xml:769
  1.9778 +msgid ""
  1.9779 +"The <command role=\"hg-cmd\">hg bisect</command> command is aware of the "
  1.9780 +"<quote>branchy</quote> nature of a Mercurial project's revision history, so "
  1.9781 +"it has no problems dealing with branches, merges, or multiple heads in a "
  1.9782 +"repository.  It can prune entire branches of history with a single probe, "
  1.9783 +"which is how it operates so efficiently."
  1.9784 +msgstr ""
  1.9785 +
  1.9786 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9787 +#: ../en/ch09-undo.xml:777
  1.9788 +msgid "Using the <command role=\"hg-cmd\">hg bisect</command> command"
  1.9789 +msgstr ""
  1.9790 +
  1.9791 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9792 +#: ../en/ch09-undo.xml:780
  1.9793 +msgid ""
  1.9794 +"Here's an example of <command role=\"hg-cmd\">hg bisect</command> in action."
  1.9795 +msgstr ""
  1.9796 +
  1.9797 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
  1.9798 +#: ../en/ch09-undo.xml:784
  1.9799 +msgid ""
  1.9800 +"In versions 0.9.5 and earlier of Mercurial, <command role=\"hg-cmd\">hg "
  1.9801 +"bisect</command> was not a core command: it was distributed with Mercurial as "
  1.9802 +"an extension. This section describes the built-in command, not the old "
  1.9803 +"extension."
  1.9804 +msgstr ""
  1.9805 +
  1.9806 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9807 +#: ../en/ch09-undo.xml:791
  1.9808 +msgid ""
  1.9809 +"Now let's create a repository, so that we can try out the <command role=\"hg-"
  1.9810 +"cmd\">hg bisect</command> command in isolation."
  1.9811 +msgstr ""
  1.9812 +
  1.9813 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9814 +#: ../en/ch09-undo.xml:797
  1.9815 +msgid ""
  1.9816 +"We'll simulate a project that has a bug in it in a simple-minded way: create "
  1.9817 +"trivial changes in a loop, and nominate one specific change that will have "
  1.9818 +"the <quote>bug</quote>.  This loop creates 35 changesets, each adding a "
  1.9819 +"single file to the repository. We'll represent our <quote>bug</quote> with a "
  1.9820 +"file that contains the text <quote>i have a gub</quote>."
  1.9821 +msgstr ""
  1.9822 +
  1.9823 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9824 +#: ../en/ch09-undo.xml:807
  1.9825 +msgid ""
  1.9826 +"The next thing that we'd like to do is figure out how to use the <command "
  1.9827 +"role=\"hg-cmd\">hg bisect</command> command.  We can use Mercurial's normal "
  1.9828 +"built-in help mechanism for this."
  1.9829 +msgstr ""
  1.9830 +
  1.9831 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9832 +#: ../en/ch09-undo.xml:814
  1.9833 +msgid ""
  1.9834 +"The <command role=\"hg-cmd\">hg bisect</command> command works in steps.  "
  1.9835 +"Each step proceeds as follows."
  1.9836 +msgstr ""
  1.9837 +
  1.9838 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9839 +#: ../en/ch09-undo.xml:817
  1.9840 +msgid "You run your binary test."
  1.9841 +msgstr ""
  1.9842 +
  1.9843 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><itemizedlist><listitem><para>
  1.9844 +#: ../en/ch09-undo.xml:819
  1.9845 +msgid ""
  1.9846 +"If the test succeeded, you tell <command role=\"hg-cmd\">hg bisect</command> "
  1.9847 +"by running the <command role=\"hg-cmd\">hg bisect good</command> command."
  1.9848 +msgstr ""
  1.9849 +
  1.9850 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><itemizedlist><listitem><para>
  1.9851 +#: ../en/ch09-undo.xml:824
  1.9852 +msgid ""
  1.9853 +"If it failed, run the <command role=\"hg-cmd\">hg bisect bad</command> "
  1.9854 +"command."
  1.9855 +msgstr ""
  1.9856 +
  1.9857 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9858 +#: ../en/ch09-undo.xml:828
  1.9859 +msgid ""
  1.9860 +"The command uses your information to decide which changeset to test next."
  1.9861 +msgstr ""
  1.9862 +
  1.9863 +#. type: Content of: <book><chapter><sect1><sect2><orderedlist><listitem><para>
  1.9864 +#: ../en/ch09-undo.xml:831
  1.9865 +msgid ""
  1.9866 +"It updates the working directory to that changeset, and the process begins "
  1.9867 +"again."
  1.9868 +msgstr ""
  1.9869 +
  1.9870 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9871 +#: ../en/ch09-undo.xml:834
  1.9872 +msgid ""
  1.9873 +"The process ends when <command role=\"hg-cmd\">hg bisect</command> identifies "
  1.9874 +"a unique changeset that marks the point where your test transitioned from "
  1.9875 +"<quote>succeeding</quote> to <quote>failing</quote>."
  1.9876 +msgstr ""
  1.9877 +
  1.9878 +#
  1.9879 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9880 +#: ../en/ch09-undo.xml:839
  1.9881 +msgid ""
  1.9882 +"To start the search, we must run the <command role=\"hg-cmd\">hg bisect --"
  1.9883 +"reset</command> command."
  1.9884 +msgstr ""
  1.9885 +
  1.9886 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9887 +#: ../en/ch09-undo.xml:844
  1.9888 +msgid ""
  1.9889 +"In our case, the binary test we use is simple: we check to see if any file in "
  1.9890 +"the repository contains the string <quote>i have a gub</quote>.  If it does, "
  1.9891 +"this changeset contains the change that <quote>caused the bug</quote>.  By "
  1.9892 +"convention, a changeset that has the property we're searching for is "
  1.9893 +"<quote>bad</quote>, while one that doesn't is <quote>good</quote>."
  1.9894 +msgstr ""
  1.9895 +
  1.9896 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9897 +#: ../en/ch09-undo.xml:852
  1.9898 +msgid ""
  1.9899 +"Most of the time, the revision to which the working directory is synced "
  1.9900 +"(usually the tip) already exhibits the problem introduced by the buggy "
  1.9901 +"change, so we'll mark it as <quote>bad</quote>."
  1.9902 +msgstr ""
  1.9903 +
  1.9904 +#
  1.9905 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9906 +#: ../en/ch09-undo.xml:859
  1.9907 +msgid ""
  1.9908 +"Our next task is to nominate a changeset that we know <emphasis>doesn't</"
  1.9909 +"emphasis> have the bug; the <command role=\"hg-cmd\">hg bisect</command> "
  1.9910 +"command will <quote>bracket</quote> its search between the first pair of good "
  1.9911 +"and bad changesets.  In our case, we know that revision 10 didn't have the "
  1.9912 +"bug.  (I'll have more words about choosing the first <quote>good</quote> "
  1.9913 +"changeset later.)"
  1.9914 +msgstr ""
  1.9915 +
  1.9916 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9917 +#: ../en/ch09-undo.xml:869
  1.9918 +msgid "Notice that this command printed some output."
  1.9919 +msgstr ""
  1.9920 +
  1.9921 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.9922 +#: ../en/ch09-undo.xml:871
  1.9923 +msgid ""
  1.9924 +"It told us how many changesets it must consider before it can identify the "
  1.9925 +"one that introduced the bug, and how many tests that will require."
  1.9926 +msgstr ""
  1.9927 +
  1.9928 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
  1.9929 +#: ../en/ch09-undo.xml:875
  1.9930 +msgid ""
  1.9931 +"It updated the working directory to the next changeset to test, and told us "
  1.9932 +"which changeset it's testing."
  1.9933 +msgstr ""
  1.9934 +
  1.9935 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9936 +#: ../en/ch09-undo.xml:880
  1.9937 +msgid ""
  1.9938 +"We now run our test in the working directory.  We use the <command>grep</"
  1.9939 +"command> command to see if our <quote>bad</quote> file is present in the "
  1.9940 +"working directory.  If it is, this revision is bad; if not, this revision is "
  1.9941 +"good.  &interaction.bisect.search.step1;"
  1.9942 +msgstr ""
  1.9943 +
  1.9944 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9945 +#: ../en/ch09-undo.xml:886
  1.9946 +msgid ""
  1.9947 +"This test looks like a perfect candidate for automation, so let's turn it "
  1.9948 +"into a shell function."
  1.9949 +msgstr ""
  1.9950 +
  1.9951 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9952 +#: ../en/ch09-undo.xml:890
  1.9953 +msgid ""
  1.9954 +"We can now run an entire test step with a single command, <literal>mytest</"
  1.9955 +"literal>."
  1.9956 +msgstr ""
  1.9957 +
  1.9958 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9959 +#: ../en/ch09-undo.xml:895
  1.9960 +msgid "A few more invocations of our canned test step command, and we're done."
  1.9961 +msgstr ""
  1.9962 +
  1.9963 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9964 +#: ../en/ch09-undo.xml:900
  1.9965 +msgid ""
  1.9966 +"Even though we had 40 changesets to search through, the <command role=\"hg-cmd"
  1.9967 +"\">hg bisect</command> command let us find the changeset that introduced our "
  1.9968 +"<quote>bug</quote> with only five tests.  Because the number of tests that "
  1.9969 +"the <command role=\"hg-cmd\">hg bisect</command> command performs grows "
  1.9970 +"logarithmically with the number of changesets to search, the advantage that "
  1.9971 +"it has over the <quote>brute force</quote> search approach increases with "
  1.9972 +"every changeset you add."
  1.9973 +msgstr ""
  1.9974 +
  1.9975 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9976 +#: ../en/ch09-undo.xml:911
  1.9977 +msgid "Cleaning up after your search"
  1.9978 +msgstr ""
  1.9979 +
  1.9980 +#
  1.9981 +#. type: Content of: <book><chapter><sect1><sect2><para>
  1.9982 +#: ../en/ch09-undo.xml:913
  1.9983 +msgid ""
  1.9984 +"When you're finished using the <command role=\"hg-cmd\">hg bisect</command> "
  1.9985 +"command in a repository, you can use the <command role=\"hg-cmd\">hg bisect "
  1.9986 +"reset</command> command to drop the information it was using to drive your "
  1.9987 +"search.  The command doesn't use much space, so it doesn't matter if you "
  1.9988 +"forget to run this command.  However, <command role=\"hg-cmd\">hg bisect</"
  1.9989 +"command> won't let you start a new search in that repository until you do a "
  1.9990 +"<command role=\"hg-cmd\">hg bisect reset</command>."
  1.9991 +msgstr ""
  1.9992 +
  1.9993 +#. type: Content of: <book><chapter><sect1><title>
  1.9994 +#: ../en/ch09-undo.xml:928
  1.9995 +msgid "Tips for finding bugs effectively"
  1.9996 +msgstr ""
  1.9997 +
  1.9998 +#. type: Content of: <book><chapter><sect1><sect2><title>
  1.9999 +#: ../en/ch09-undo.xml:931
 1.10000 +msgid "Give consistent input"
 1.10001 +msgstr ""
 1.10002 +
 1.10003 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10004 +#: ../en/ch09-undo.xml:933
 1.10005 +msgid ""
 1.10006 +"The <command role=\"hg-cmd\">hg bisect</command> command requires that you "
 1.10007 +"correctly report the result of every test you perform.  If you tell it that a "
 1.10008 +"test failed when it really succeeded, it <emphasis>might</emphasis> be able "
 1.10009 +"to detect the inconsistency.  If it can identify an inconsistency in your "
 1.10010 +"reports, it will tell you that a particular changeset is both good and bad. "
 1.10011 +"However, it can't do this perfectly; it's about as likely to report the wrong "
 1.10012 +"changeset as the source of the bug."
 1.10013 +msgstr ""
 1.10014 +
 1.10015 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10016 +#: ../en/ch09-undo.xml:945
 1.10017 +msgid "Automate as much as possible"
 1.10018 +msgstr ""
 1.10019 +
 1.10020 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10021 +#: ../en/ch09-undo.xml:947
 1.10022 +msgid ""
 1.10023 +"When I started using the <command role=\"hg-cmd\">hg bisect</command> "
 1.10024 +"command, I tried a few times to run my tests by hand, on the command line.  "
 1.10025 +"This is an approach that I, at least, am not suited to.  After a few tries, I "
 1.10026 +"found that I was making enough mistakes that I was having to restart my "
 1.10027 +"searches several times before finally getting correct results."
 1.10028 +msgstr ""
 1.10029 +
 1.10030 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10031 +#: ../en/ch09-undo.xml:955
 1.10032 +msgid ""
 1.10033 +"My initial problems with driving the <command role=\"hg-cmd\">hg bisect</"
 1.10034 +"command> command by hand occurred even with simple searches on small "
 1.10035 +"repositories; if the problem you're looking for is more subtle, or the number "
 1.10036 +"of tests that <command role=\"hg-cmd\">hg bisect</command> must perform "
 1.10037 +"increases, the likelihood of operator error ruining the search is much "
 1.10038 +"higher.  Once I started automating my tests, I had much better results."
 1.10039 +msgstr ""
 1.10040 +
 1.10041 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10042 +#: ../en/ch09-undo.xml:964
 1.10043 +msgid "The key to automated testing is twofold:"
 1.10044 +msgstr ""
 1.10045 +
 1.10046 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.10047 +#: ../en/ch09-undo.xml:966
 1.10048 +msgid "always test for the same symptom, and"
 1.10049 +msgstr ""
 1.10050 +
 1.10051 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.10052 +#: ../en/ch09-undo.xml:968
 1.10053 +msgid ""
 1.10054 +"always feed consistent input to the <command role=\"hg-cmd\">hg bisect</"
 1.10055 +"command> command."
 1.10056 +msgstr ""
 1.10057 +
 1.10058 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10059 +#: ../en/ch09-undo.xml:971
 1.10060 +msgid ""
 1.10061 +"In my tutorial example above, the <command>grep</command> command tests for "
 1.10062 +"the symptom, and the <literal>if</literal> statement takes the result of this "
 1.10063 +"check and ensures that we always feed the same input to the <command role="
 1.10064 +"\"hg-cmd\">hg bisect</command> command.  The <literal>mytest</literal> "
 1.10065 +"function marries these together in a reproducible way, so that every test is "
 1.10066 +"uniform and consistent."
 1.10067 +msgstr ""
 1.10068 +
 1.10069 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10070 +#: ../en/ch09-undo.xml:981
 1.10071 +msgid "Check your results"
 1.10072 +msgstr ""
 1.10073 +
 1.10074 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10075 +#: ../en/ch09-undo.xml:983
 1.10076 +msgid ""
 1.10077 +"Because the output of a <command role=\"hg-cmd\">hg bisect</command> search "
 1.10078 +"is only as good as the input you give it, don't take the changeset it reports "
 1.10079 +"as the absolute truth.  A simple way to cross-check its report is to manually "
 1.10080 +"run your test at each of the following changesets:"
 1.10081 +msgstr ""
 1.10082 +
 1.10083 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.10084 +#: ../en/ch09-undo.xml:989
 1.10085 +msgid ""
 1.10086 +"The changeset that it reports as the first bad revision.  Your test should "
 1.10087 +"still report this as bad."
 1.10088 +msgstr ""
 1.10089 +
 1.10090 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.10091 +#: ../en/ch09-undo.xml:993
 1.10092 +msgid ""
 1.10093 +"The parent of that changeset (either parent, if it's a merge). Your test "
 1.10094 +"should report this changeset as good."
 1.10095 +msgstr ""
 1.10096 +
 1.10097 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.10098 +#: ../en/ch09-undo.xml:997
 1.10099 +msgid ""
 1.10100 +"A child of that changeset.  Your test should report this changeset as bad."
 1.10101 +msgstr ""
 1.10102 +
 1.10103 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10104 +#: ../en/ch09-undo.xml:1003
 1.10105 +msgid "Beware interference between bugs"
 1.10106 +msgstr ""
 1.10107 +
 1.10108 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10109 +#: ../en/ch09-undo.xml:1005
 1.10110 +msgid ""
 1.10111 +"It's possible that your search for one bug could be disrupted by the presence "
 1.10112 +"of another.  For example, let's say your software crashes at revision 100, "
 1.10113 +"and worked correctly at revision 50.  Unknown to you, someone else introduced "
 1.10114 +"a different crashing bug at revision 60, and fixed it at revision 80.  This "
 1.10115 +"could distort your results in one of several ways."
 1.10116 +msgstr ""
 1.10117 +
 1.10118 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10119 +#: ../en/ch09-undo.xml:1013
 1.10120 +msgid ""
 1.10121 +"It is possible that this other bug completely <quote>masks</quote> yours, "
 1.10122 +"which is to say that it occurs before your bug has a chance to manifest "
 1.10123 +"itself.  If you can't avoid that other bug (for example, it prevents your "
 1.10124 +"project from building), and so can't tell whether your bug is present in a "
 1.10125 +"particular changeset, the <command role=\"hg-cmd\">hg bisect</command> "
 1.10126 +"command cannot help you directly.  Instead, you can mark a changeset as "
 1.10127 +"untested by running <command role=\"hg-cmd\">hg bisect --skip</command>."
 1.10128 +msgstr ""
 1.10129 +
 1.10130 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10131 +#: ../en/ch09-undo.xml:1023
 1.10132 +msgid ""
 1.10133 +"A different problem could arise if your test for a bug's presence is not "
 1.10134 +"specific enough.  If you check for <quote>my program crashes</quote>, then "
 1.10135 +"both your crashing bug and an unrelated crashing bug that masks it will look "
 1.10136 +"like the same thing, and mislead <command role=\"hg-cmd\">hg bisect</command>."
 1.10137 +msgstr ""
 1.10138 +
 1.10139 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10140 +#: ../en/ch09-undo.xml:1030
 1.10141 +msgid ""
 1.10142 +"Another useful situation in which to use <command role=\"hg-cmd\">hg bisect --"
 1.10143 +"skip</command> is if you can't test a revision because your project was in a "
 1.10144 +"broken and hence untestable state at that revision, perhaps because someone "
 1.10145 +"checked in a change that prevented the project from building."
 1.10146 +msgstr ""
 1.10147 +
 1.10148 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10149 +#: ../en/ch09-undo.xml:1039
 1.10150 +msgid "Bracket your search lazily"
 1.10151 +msgstr ""
 1.10152 +
 1.10153 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10154 +#: ../en/ch09-undo.xml:1041
 1.10155 +msgid ""
 1.10156 +"Choosing the first <quote>good</quote> and <quote>bad</quote> changesets that "
 1.10157 +"will mark the end points of your search is often easy, but it bears a little "
 1.10158 +"discussion nevertheless.  From the perspective of <command role=\"hg-cmd\">hg "
 1.10159 +"bisect</command>, the <quote>newest</quote> changeset is conventionally "
 1.10160 +"<quote>bad</quote>, and the older changeset is <quote>good</quote>."
 1.10161 +msgstr ""
 1.10162 +
 1.10163 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10164 +#: ../en/ch09-undo.xml:1049
 1.10165 +msgid ""
 1.10166 +"If you're having trouble remembering when a suitable <quote>good</quote> "
 1.10167 +"change was, so that you can tell <command role=\"hg-cmd\">hg bisect</"
 1.10168 +"command>, you could do worse than testing changesets at random.  Just "
 1.10169 +"remember to eliminate contenders that can't possibly exhibit the bug (perhaps "
 1.10170 +"because the feature with the bug isn't present yet) and those where another "
 1.10171 +"problem masks the bug (as I discussed above)."
 1.10172 +msgstr ""
 1.10173 +
 1.10174 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10175 +#: ../en/ch09-undo.xml:1058
 1.10176 +msgid ""
 1.10177 +"Even if you end up <quote>early</quote> by thousands of changesets or months "
 1.10178 +"of history, you will only add a handful of tests to the total number that "
 1.10179 +"<command role=\"hg-cmd\">hg bisect</command> must perform, thanks to its "
 1.10180 +"logarithmic behaviour."
 1.10181 +msgstr ""
 1.10182 +
 1.10183 +#. type: Content of: <book><chapter><title>
 1.10184 +#: ../en/ch10-hook.xml:5
 1.10185 +msgid "Handling repository events with hooks"
 1.10186 +msgstr "使用钩子处理版本库事件"
 1.10187 +
 1.10188 +#. type: Content of: <book><chapter><para>
 1.10189 +#: ../en/ch10-hook.xml:7
 1.10190 +msgid ""
 1.10191 +"Mercurial offers a powerful mechanism to let you perform automated actions in "
 1.10192 +"response to events that occur in a repository.  In some cases, you can even "
 1.10193 +"control Mercurial's response to those events."
 1.10194 +msgstr ""
 1.10195 +
 1.10196 +#. type: Content of: <book><chapter><para>
 1.10197 +#: ../en/ch10-hook.xml:12
 1.10198 +msgid ""
 1.10199 +"The name Mercurial uses for one of these actions is a <emphasis>hook</"
 1.10200 +"emphasis>. Hooks are called <quote>triggers</quote> in some revision control "
 1.10201 +"systems, but the two names refer to the same idea."
 1.10202 +msgstr ""
 1.10203 +
 1.10204 +#. type: Content of: <book><chapter><sect1><title>
 1.10205 +#: ../en/ch10-hook.xml:18
 1.10206 +msgid "An overview of hooks in Mercurial"
 1.10207 +msgstr ""
 1.10208 +
 1.10209 +#. type: Content of: <book><chapter><sect1><para>
 1.10210 +#: ../en/ch10-hook.xml:20
 1.10211 +msgid ""
 1.10212 +"Here is a brief list of the hooks that Mercurial supports.  We will revisit "
 1.10213 +"each of these hooks in more detail later, in section <xref linkend=\"sec.hook."
 1.10214 +"ref\"/>."
 1.10215 +msgstr ""
 1.10216 +
 1.10217 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10218 +#: ../en/ch10-hook.xml:25
 1.10219 +msgid ""
 1.10220 +"<literal role=\"hook\">changegroup</literal>: This is run after a group of "
 1.10221 +"changesets has been brought into the repository from elsewhere."
 1.10222 +msgstr ""
 1.10223 +
 1.10224 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10225 +#: ../en/ch10-hook.xml:29
 1.10226 +msgid ""
 1.10227 +"<literal role=\"hook\">commit</literal>: This is run after a new changeset "
 1.10228 +"has been created in the local repository."
 1.10229 +msgstr ""
 1.10230 +
 1.10231 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10232 +#: ../en/ch10-hook.xml:33
 1.10233 +msgid ""
 1.10234 +"<literal role=\"hook\">incoming</literal>: This is run once for each new "
 1.10235 +"changeset that is brought into the repository from elsewhere.  Notice the "
 1.10236 +"difference from <literal role=\"hook\">changegroup</literal>, which is run "
 1.10237 +"once per <emphasis>group</emphasis> of changesets brought in."
 1.10238 +msgstr ""
 1.10239 +
 1.10240 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10241 +#: ../en/ch10-hook.xml:40
 1.10242 +msgid ""
 1.10243 +"<literal role=\"hook\">outgoing</literal>: This is run after a group of "
 1.10244 +"changesets has been transmitted from this repository."
 1.10245 +msgstr ""
 1.10246 +
 1.10247 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10248 +#: ../en/ch10-hook.xml:44
 1.10249 +msgid ""
 1.10250 +"<literal role=\"hook\">prechangegroup</literal>: This is run before starting "
 1.10251 +"to bring a group of changesets into the repository."
 1.10252 +msgstr ""
 1.10253 +
 1.10254 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10255 +#: ../en/ch10-hook.xml:49
 1.10256 +msgid ""
 1.10257 +"<literal role=\"hook\">precommit</literal>: Controlling. This is run before "
 1.10258 +"starting a commit."
 1.10259 +msgstr ""
 1.10260 +
 1.10261 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10262 +#: ../en/ch10-hook.xml:53
 1.10263 +msgid ""
 1.10264 +"<literal role=\"hook\">preoutgoing</literal>: Controlling. This is run before "
 1.10265 +"starting to transmit a group of changesets from this repository."
 1.10266 +msgstr ""
 1.10267 +
 1.10268 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10269 +#: ../en/ch10-hook.xml:58
 1.10270 +msgid ""
 1.10271 +"<literal role=\"hook\">pretag</literal>: Controlling. This is run before "
 1.10272 +"creating a tag."
 1.10273 +msgstr ""
 1.10274 +
 1.10275 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10276 +#: ../en/ch10-hook.xml:62
 1.10277 +msgid ""
 1.10278 +"<literal role=\"hook\">pretxnchangegroup</literal>: Controlling. This is run "
 1.10279 +"after a group of changesets has been brought into the local repository from "
 1.10280 +"another, but before the transaction completes that will make the changes "
 1.10281 +"permanent in the repository."
 1.10282 +msgstr ""
 1.10283 +
 1.10284 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10285 +#: ../en/ch10-hook.xml:70
 1.10286 +msgid ""
 1.10287 +"<literal role=\"hook\">pretxncommit</literal>: Controlling. This is run after "
 1.10288 +"a new changeset has been created in the local repository, but before the "
 1.10289 +"transaction completes that will make it permanent."
 1.10290 +msgstr ""
 1.10291 +
 1.10292 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10293 +#: ../en/ch10-hook.xml:76
 1.10294 +msgid ""
 1.10295 +"<literal role=\"hook\">preupdate</literal>: Controlling. This is run before "
 1.10296 +"starting an update or merge of the working directory."
 1.10297 +msgstr ""
 1.10298 +
 1.10299 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10300 +#: ../en/ch10-hook.xml:81
 1.10301 +msgid ""
 1.10302 +"<literal role=\"hook\">tag</literal>: This is run after a tag is created."
 1.10303 +msgstr ""
 1.10304 +
 1.10305 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.10306 +#: ../en/ch10-hook.xml:85
 1.10307 +msgid ""
 1.10308 +"<literal role=\"hook\">update</literal>: This is run after an update or merge "
 1.10309 +"of the working directory has finished."
 1.10310 +msgstr ""
 1.10311 +
 1.10312 +#. type: Content of: <book><chapter><sect1><para>
 1.10313 +#: ../en/ch10-hook.xml:90
 1.10314 +msgid ""
 1.10315 +"Each of the hooks whose description begins with the word <quote>Controlling</"
 1.10316 +"quote> has the ability to determine whether an activity can proceed.  If the "
 1.10317 +"hook succeeds, the activity may proceed; if it fails, the activity is either "
 1.10318 +"not permitted or undone, depending on the hook."
 1.10319 +msgstr ""
 1.10320 +
 1.10321 +#. type: Content of: <book><chapter><sect1><title>
 1.10322 +#: ../en/ch10-hook.xml:99
 1.10323 +msgid "Hooks and security"
 1.10324 +msgstr ""
 1.10325 +
 1.10326 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10327 +#: ../en/ch10-hook.xml:102
 1.10328 +msgid "Hooks are run with your privileges"
 1.10329 +msgstr ""
 1.10330 +
 1.10331 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10332 +#: ../en/ch10-hook.xml:104
 1.10333 +msgid ""
 1.10334 +"When you run a Mercurial command in a repository, and the command causes a "
 1.10335 +"hook to run, that hook runs on <emphasis>your</emphasis> system, under "
 1.10336 +"<emphasis>your</emphasis> user account, with <emphasis>your</emphasis> "
 1.10337 +"privilege level.  Since hooks are arbitrary pieces of executable code, you "
 1.10338 +"should treat them with an appropriate level of suspicion.  Do not install a "
 1.10339 +"hook unless you are confident that you know who created it and what it does."
 1.10340 +msgstr ""
 1.10341 +
 1.10342 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10343 +#: ../en/ch10-hook.xml:115
 1.10344 +msgid ""
 1.10345 +"In some cases, you may be exposed to hooks that you did not install "
 1.10346 +"yourself.  If you work with Mercurial on an unfamiliar system, Mercurial will "
 1.10347 +"run hooks defined in that system's global <filename role=\"special\"> /.hgrc</"
 1.10348 +"filename>\\ file."
 1.10349 +msgstr ""
 1.10350 +
 1.10351 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10352 +#: ../en/ch10-hook.xml:122
 1.10353 +msgid ""
 1.10354 +"If you are working with a repository owned by another user, Mercurial can run "
 1.10355 +"hooks defined in that user's repository, but it will still run them as "
 1.10356 +"<quote>you</quote>.  For example, if you <command role=\"hg-cmd\">hg pull</"
 1.10357 +"command> from that repository, and its <filename role=\"special\">.hg/hgrc</"
 1.10358 +"filename> defines a local <literal role=\"hook\">outgoing</literal> hook, "
 1.10359 +"that hook will run under your user account, even though you don't own that "
 1.10360 +"repository."
 1.10361 +msgstr ""
 1.10362 +
 1.10363 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
 1.10364 +#: ../en/ch10-hook.xml:134
 1.10365 +msgid ""
 1.10366 +"This only applies if you are pulling from a repository on a local or network "
 1.10367 +"filesystem.  If you're pulling over http or ssh, any <literal role=\"hook"
 1.10368 +"\">outgoing</literal> hook will run under whatever account is executing the "
 1.10369 +"server process, on the server."
 1.10370 +msgstr ""
 1.10371 +
 1.10372 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10373 +#: ../en/ch10-hook.xml:142
 1.10374 +msgid ""
 1.10375 +"XXX To see what hooks are defined in a repository, use the <command role=\"hg-"
 1.10376 +"cmd\">hg config hooks</command> command.  If you are working in one "
 1.10377 +"repository, but talking to another that you do not own (e.g. using <command "
 1.10378 +"role=\"hg-cmd\">hg pull</command> or <command role=\"hg-cmd\">hg incoming</"
 1.10379 +"command>), remember that it is the other repository's hooks you should be "
 1.10380 +"checking, not your own."
 1.10381 +msgstr ""
 1.10382 +
 1.10383 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10384 +#: ../en/ch10-hook.xml:153
 1.10385 +msgid "Hooks do not propagate"
 1.10386 +msgstr ""
 1.10387 +
 1.10388 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10389 +#: ../en/ch10-hook.xml:155
 1.10390 +msgid ""
 1.10391 +"In Mercurial, hooks are not revision controlled, and do not propagate when "
 1.10392 +"you clone, or pull from, a repository.  The reason for this is simple: a hook "
 1.10393 +"is a completely arbitrary piece of executable code.  It runs under your user "
 1.10394 +"identity, with your privilege level, on your machine."
 1.10395 +msgstr ""
 1.10396 +
 1.10397 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10398 +#: ../en/ch10-hook.xml:162
 1.10399 +msgid ""
 1.10400 +"It would be extremely reckless for any distributed revision control system to "
 1.10401 +"implement revision-controlled hooks, as this would offer an easily "
 1.10402 +"exploitable way to subvert the accounts of users of the revision control "
 1.10403 +"system."
 1.10404 +msgstr ""
 1.10405 +
 1.10406 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10407 +#: ../en/ch10-hook.xml:168
 1.10408 +msgid ""
 1.10409 +"Since Mercurial does not propagate hooks, if you are collaborating with other "
 1.10410 +"people on a common project, you should not assume that they are using the "
 1.10411 +"same Mercurial hooks as you are, or that theirs are correctly configured.  "
 1.10412 +"You should document the hooks you expect people to use."
 1.10413 +msgstr ""
 1.10414 +
 1.10415 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10416 +#: ../en/ch10-hook.xml:175
 1.10417 +msgid ""
 1.10418 +"In a corporate intranet, this is somewhat easier to control, as you can for "
 1.10419 +"example provide a <quote>standard</quote> installation of Mercurial on an NFS "
 1.10420 +"filesystem, and use a site-wide <filename role=\"special\"> /.hgrc</filename>"
 1.10421 +"\\ file to define hooks that all users will see.  However, this too has its "
 1.10422 +"limits; see below."
 1.10423 +msgstr ""
 1.10424 +
 1.10425 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10426 +#: ../en/ch10-hook.xml:185
 1.10427 +msgid "Hooks can be overridden"
 1.10428 +msgstr ""
 1.10429 +
 1.10430 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10431 +#: ../en/ch10-hook.xml:187
 1.10432 +msgid ""
 1.10433 +"Mercurial allows you to override a hook definition by redefining the hook.  "
 1.10434 +"You can disable it by setting its value to the empty string, or change its "
 1.10435 +"behaviour as you wish."
 1.10436 +msgstr ""
 1.10437 +
 1.10438 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10439 +#: ../en/ch10-hook.xml:192
 1.10440 +msgid ""
 1.10441 +"If you deploy a system- or site-wide <filename role=\"special\"> /.hgrc</"
 1.10442 +"filename>\\ file that defines some hooks, you should thus understand that "
 1.10443 +"your users can disable or override those hooks."
 1.10444 +msgstr ""
 1.10445 +
 1.10446 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10447 +#: ../en/ch10-hook.xml:200
 1.10448 +msgid "Ensuring that critical hooks are run"
 1.10449 +msgstr ""
 1.10450 +
 1.10451 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10452 +#: ../en/ch10-hook.xml:202
 1.10453 +msgid ""
 1.10454 +"Sometimes you may want to enforce a policy that you do not want others to be "
 1.10455 +"able to work around.  For example, you may have a requirement that every "
 1.10456 +"changeset must pass a rigorous set of tests.  Defining this requirement via a "
 1.10457 +"hook in a site-wide <filename role=\"special\"> /.hgrc</filename>\\ won't "
 1.10458 +"work for remote users on laptops, and of course local users can subvert it at "
 1.10459 +"will by overriding the hook."
 1.10460 +msgstr ""
 1.10461 +
 1.10462 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10463 +#: ../en/ch10-hook.xml:211
 1.10464 +msgid ""
 1.10465 +"Instead, you can set up your policies for use of Mercurial so that people are "
 1.10466 +"expected to propagate changes through a well-known <quote>canonical</quote> "
 1.10467 +"server that you have locked down and configured appropriately."
 1.10468 +msgstr ""
 1.10469 +
 1.10470 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10471 +#: ../en/ch10-hook.xml:217
 1.10472 +msgid ""
 1.10473 +"One way to do this is via a combination of social engineering and "
 1.10474 +"technology.  Set up a restricted-access account; users can push changes over "
 1.10475 +"the network to repositories managed by this account, but they cannot log into "
 1.10476 +"the account and run normal shell commands.  In this scenario, a user can "
 1.10477 +"commit a changeset that contains any old garbage they want."
 1.10478 +msgstr ""
 1.10479 +
 1.10480 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10481 +#: ../en/ch10-hook.xml:226
 1.10482 +msgid ""
 1.10483 +"When someone pushes a changeset to the server that everyone pulls from, the "
 1.10484 +"server will test the changeset before it accepts it as permanent, and reject "
 1.10485 +"it if it fails to pass the test suite.  If people only pull changes from this "
 1.10486 +"filtering server, it will serve to ensure that all changes that people pull "
 1.10487 +"have been automatically vetted."
 1.10488 +msgstr ""
 1.10489 +
 1.10490 +#. type: Content of: <book><chapter><sect1><title>
 1.10491 +#: ../en/ch10-hook.xml:237
 1.10492 +msgid "Care with <literal>pretxn</literal> hooks in a shared-access repository"
 1.10493 +msgstr ""
 1.10494 +
 1.10495 +#. type: Content of: <book><chapter><sect1><para>
 1.10496 +#: ../en/ch10-hook.xml:240
 1.10497 +msgid ""
 1.10498 +"If you want to use hooks to do some automated work in a repository that a "
 1.10499 +"number of people have shared access to, you need to be careful in how you do "
 1.10500 +"this."
 1.10501 +msgstr ""
 1.10502 +
 1.10503 +#. type: Content of: <book><chapter><sect1><para>
 1.10504 +#: ../en/ch10-hook.xml:245
 1.10505 +msgid ""
 1.10506 +"Mercurial only locks a repository when it is writing to the repository, and "
 1.10507 +"only the parts of Mercurial that write to the repository pay attention to "
 1.10508 +"locks.  Write locks are necessary to prevent multiple simultaneous writers "
 1.10509 +"from scribbling on each other's work, corrupting the repository."
 1.10510 +msgstr ""
 1.10511 +
 1.10512 +#. type: Content of: <book><chapter><sect1><para>
 1.10513 +#: ../en/ch10-hook.xml:252
 1.10514 +msgid ""
 1.10515 +"Because Mercurial is careful with the order in which it reads and writes "
 1.10516 +"data, it does not need to acquire a lock when it wants to read data from the "
 1.10517 +"repository.  The parts of Mercurial that read from the repository never pay "
 1.10518 +"attention to locks.  This lockless reading scheme greatly increases "
 1.10519 +"performance and concurrency."
 1.10520 +msgstr ""
 1.10521 +
 1.10522 +#. type: Content of: <book><chapter><sect1><para>
 1.10523 +#: ../en/ch10-hook.xml:260
 1.10524 +msgid ""
 1.10525 +"With great performance comes a trade-off, though, one which has the potential "
 1.10526 +"to cause you trouble unless you're aware of it.  To describe this requires a "
 1.10527 +"little detail about how Mercurial adds changesets to a repository and reads "
 1.10528 +"those changes."
 1.10529 +msgstr ""
 1.10530 +
 1.10531 +#. type: Content of: <book><chapter><sect1><para>
 1.10532 +#: ../en/ch10-hook.xml:267
 1.10533 +msgid ""
 1.10534 +"When Mercurial <emphasis>writes</emphasis> metadata, it writes it straight "
 1.10535 +"into the destination file.  It writes file data first, then manifest data "
 1.10536 +"(which contains pointers to the new file data), then changelog data (which "
 1.10537 +"contains pointers to the new manifest data).  Before the first write to each "
 1.10538 +"file, it stores a record of where the end of the file was in its transaction "
 1.10539 +"log.  If the transaction must be rolled back, Mercurial simply truncates each "
 1.10540 +"file back to the size it was before the transaction began."
 1.10541 +msgstr ""
 1.10542 +
 1.10543 +#. type: Content of: <book><chapter><sect1><para>
 1.10544 +#: ../en/ch10-hook.xml:278
 1.10545 +msgid ""
 1.10546 +"When Mercurial <emphasis>reads</emphasis> metadata, it reads the changelog "
 1.10547 +"first, then everything else.  Since a reader will only access parts of the "
 1.10548 +"manifest or file metadata that it can see in the changelog, it can never see "
 1.10549 +"partially written data."
 1.10550 +msgstr ""
 1.10551 +
 1.10552 +#. type: Content of: <book><chapter><sect1><para>
 1.10553 +#: ../en/ch10-hook.xml:284
 1.10554 +msgid ""
 1.10555 +"Some controlling hooks (<literal role=\"hook\">pretxncommit</literal> and "
 1.10556 +"<literal role=\"hook\">pretxnchangegroup</literal>) run when a transaction is "
 1.10557 +"almost complete. All of the metadata has been written, but Mercurial can "
 1.10558 +"still roll the transaction back and cause the newly-written data to disappear."
 1.10559 +msgstr ""
 1.10560 +
 1.10561 +#. type: Content of: <book><chapter><sect1><para>
 1.10562 +#: ../en/ch10-hook.xml:292
 1.10563 +msgid ""
 1.10564 +"If one of these hooks runs for long, it opens a window of time during which a "
 1.10565 +"reader can see the metadata for changesets that are not yet permanent, and "
 1.10566 +"should not be thought of as <quote>really there</quote>.  The longer the hook "
 1.10567 +"runs, the longer that window is open."
 1.10568 +msgstr ""
 1.10569 +
 1.10570 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10571 +#: ../en/ch10-hook.xml:300
 1.10572 +msgid "The problem illustrated"
 1.10573 +msgstr ""
 1.10574 +
 1.10575 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10576 +#: ../en/ch10-hook.xml:302
 1.10577 +msgid ""
 1.10578 +"In principle, a good use for the <literal role=\"hook\">pretxnchangegroup</"
 1.10579 +"literal> hook would be to automatically build and test incoming changes "
 1.10580 +"before they are accepted into a central repository.  This could let you "
 1.10581 +"guarantee that nobody can push changes to this repository that <quote>break "
 1.10582 +"the build</quote>. But if a client can pull changes while they're being "
 1.10583 +"tested, the usefulness of the test is zero; an unsuspecting someone can pull "
 1.10584 +"untested changes, potentially breaking their build."
 1.10585 +msgstr ""
 1.10586 +
 1.10587 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10588 +#: ../en/ch10-hook.xml:313
 1.10589 +msgid ""
 1.10590 +"The safest technological answer to this challenge is to set up such a "
 1.10591 +"<quote>gatekeeper</quote> repository as <emphasis>unidirectional</emphasis>.  "
 1.10592 +"Let it take changes pushed in from the outside, but do not allow anyone to "
 1.10593 +"pull changes from it (use the <literal role=\"hook\">preoutgoing</literal> "
 1.10594 +"hook to lock it down).  Configure a <literal role=\"hook\">changegroup</"
 1.10595 +"literal> hook so that if a build or test succeeds, the hook will push the new "
 1.10596 +"changes out to another repository that people <emphasis>can</emphasis> pull "
 1.10597 +"from."
 1.10598 +msgstr ""
 1.10599 +
 1.10600 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10601 +#: ../en/ch10-hook.xml:325
 1.10602 +msgid ""
 1.10603 +"In practice, putting a centralised bottleneck like this in place is not often "
 1.10604 +"a good idea, and transaction visibility has nothing to do with the problem.  "
 1.10605 +"As the size of a project&emdash;and the time it takes to build and "
 1.10606 +"test&emdash;grows, you rapidly run into a wall with this <quote>try before "
 1.10607 +"you buy</quote> approach, where you have more changesets to test than time in "
 1.10608 +"which to deal with them.  The inevitable result is frustration on the part of "
 1.10609 +"all involved."
 1.10610 +msgstr ""
 1.10611 +
 1.10612 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10613 +#: ../en/ch10-hook.xml:336
 1.10614 +msgid ""
 1.10615 +"An approach that scales better is to get people to build and test before they "
 1.10616 +"push, then run automated builds and tests centrally <emphasis>after</"
 1.10617 +"emphasis> a push, to be sure all is well.  The advantage of this approach is "
 1.10618 +"that it does not impose a limit on the rate at which the repository can "
 1.10619 +"accept changes."
 1.10620 +msgstr ""
 1.10621 +
 1.10622 +#. type: Content of: <book><chapter><sect1><title>
 1.10623 +#: ../en/ch10-hook.xml:347
 1.10624 +msgid "A short tutorial on using hooks"
 1.10625 +msgstr ""
 1.10626 +
 1.10627 +#. type: Content of: <book><chapter><sect1><para>
 1.10628 +#: ../en/ch10-hook.xml:349
 1.10629 +msgid ""
 1.10630 +"It is easy to write a Mercurial hook.  Let's start with a hook that runs when "
 1.10631 +"you finish a <command role=\"hg-cmd\">hg commit</command>, and simply prints "
 1.10632 +"the hash of the changeset you just created.  The hook is called <literal role="
 1.10633 +"\"hook\">commit</literal>."
 1.10634 +msgstr ""
 1.10635 +
 1.10636 +#. type: Content of: <book><chapter><sect1><para>
 1.10637 +#: ../en/ch10-hook.xml:356
 1.10638 +msgid "All hooks follow the pattern in this example."
 1.10639 +msgstr ""
 1.10640 +
 1.10641 +#. type: Content of: <book><chapter><sect1><para>
 1.10642 +#: ../en/ch10-hook.xml:360
 1.10643 +msgid ""
 1.10644 +"You add an entry to the <literal role=\"rc-hooks\">hooks</literal> section of "
 1.10645 +"your <filename role=\"special\"> /.hgrc</filename>.  On the left is the name "
 1.10646 +"of the event to trigger on; on the right is the action to take.  As you can "
 1.10647 +"see, you can run an arbitrary shell command in a hook.  Mercurial passes "
 1.10648 +"extra information to the hook using environment variables (look for "
 1.10649 +"<envar>HG_NODE</envar> in the example)."
 1.10650 +msgstr ""
 1.10651 +
 1.10652 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10653 +#: ../en/ch10-hook.xml:370
 1.10654 +msgid "Performing multiple actions per event"
 1.10655 +msgstr ""
 1.10656 +
 1.10657 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10658 +#: ../en/ch10-hook.xml:372
 1.10659 +msgid ""
 1.10660 +"Quite often, you will want to define more than one hook for a particular kind "
 1.10661 +"of event, as shown below."
 1.10662 +msgstr ""
 1.10663 +
 1.10664 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10665 +#: ../en/ch10-hook.xml:377
 1.10666 +msgid ""
 1.10667 +"Mercurial lets you do this by adding an <emphasis>extension</emphasis> to the "
 1.10668 +"end of a hook's name.  You extend a hook's name by giving the name of the "
 1.10669 +"hook, followed by a full stop (the <quote><literal>.</literal></quote> "
 1.10670 +"character), followed by some more text of your choosing.  For example, "
 1.10671 +"Mercurial will run both <literal>commit.foo</literal> and <literal>commit."
 1.10672 +"bar</literal> when the <literal>commit</literal> event occurs."
 1.10673 +msgstr ""
 1.10674 +
 1.10675 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10676 +#: ../en/ch10-hook.xml:388
 1.10677 +msgid ""
 1.10678 +"To give a well-defined order of execution when there are multiple hooks "
 1.10679 +"defined for an event, Mercurial sorts hooks by extension, and executes the "
 1.10680 +"hook commands in this sorted order.  In the above example, it will execute "
 1.10681 +"<literal>commit.bar</literal> before <literal>commit.foo</literal>, and "
 1.10682 +"<literal>commit</literal> before both."
 1.10683 +msgstr ""
 1.10684 +
 1.10685 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10686 +#: ../en/ch10-hook.xml:397
 1.10687 +msgid ""
 1.10688 +"It is a good idea to use a somewhat descriptive extension when you define a "
 1.10689 +"new hook.  This will help you to remember what the hook was for.  If the hook "
 1.10690 +"fails, you'll get an error message that contains the hook name and extension, "
 1.10691 +"so using a descriptive extension could give you an immediate hint as to why "
 1.10692 +"the hook failed (see section <xref linkend=\"sec.hook.perm\"/> for an "
 1.10693 +"example)."
 1.10694 +msgstr ""
 1.10695 +
 1.10696 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10697 +#: ../en/ch10-hook.xml:408
 1.10698 +msgid "Controlling whether an activity can proceed"
 1.10699 +msgstr ""
 1.10700 +
 1.10701 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10702 +#: ../en/ch10-hook.xml:410
 1.10703 +msgid ""
 1.10704 +"In our earlier examples, we used the <literal role=\"hook\">commit</literal> "
 1.10705 +"hook, which is run after a commit has completed.  This is one of several "
 1.10706 +"Mercurial hooks that run after an activity finishes.  Such hooks have no way "
 1.10707 +"of influencing the activity itself."
 1.10708 +msgstr ""
 1.10709 +
 1.10710 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10711 +#: ../en/ch10-hook.xml:417
 1.10712 +msgid ""
 1.10713 +"Mercurial defines a number of events that occur before an activity starts; or "
 1.10714 +"after it starts, but before it finishes.  Hooks that trigger on these events "
 1.10715 +"have the added ability to choose whether the activity can continue, or will "
 1.10716 +"abort."
 1.10717 +msgstr ""
 1.10718 +
 1.10719 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10720 +#: ../en/ch10-hook.xml:423
 1.10721 +msgid ""
 1.10722 +"The <literal role=\"hook\">pretxncommit</literal> hook runs after a commit "
 1.10723 +"has all but completed.  In other words, the metadata representing the "
 1.10724 +"changeset has been written out to disk, but the transaction has not yet been "
 1.10725 +"allowed to complete.  The <literal role=\"hook\">pretxncommit</literal> hook "
 1.10726 +"has the ability to decide whether the transaction can complete, or must be "
 1.10727 +"rolled back."
 1.10728 +msgstr ""
 1.10729 +
 1.10730 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10731 +#: ../en/ch10-hook.xml:432
 1.10732 +msgid ""
 1.10733 +"If the <literal role=\"hook\">pretxncommit</literal> hook exits with a status "
 1.10734 +"code of zero, the transaction is allowed to complete; the commit finishes; "
 1.10735 +"and the <literal role=\"hook\">commit</literal> hook is run.  If the <literal "
 1.10736 +"role=\"hook\">pretxncommit</literal> hook exits with a non-zero status code, "
 1.10737 +"the transaction is rolled back; the metadata representing the changeset is "
 1.10738 +"erased; and the <literal role=\"hook\">commit</literal> hook is not run."
 1.10739 +msgstr ""
 1.10740 +
 1.10741 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10742 +#: ../en/ch10-hook.xml:444
 1.10743 +msgid ""
 1.10744 +"The hook in the example above checks that a commit comment contains a bug "
 1.10745 +"ID.  If it does, the commit can complete.  If not, the commit is rolled back."
 1.10746 +msgstr ""
 1.10747 +
 1.10748 +#. type: Content of: <book><chapter><sect1><title>
 1.10749 +#: ../en/ch10-hook.xml:452
 1.10750 +msgid "Writing your own hooks"
 1.10751 +msgstr ""
 1.10752 +
 1.10753 +#. type: Content of: <book><chapter><sect1><para>
 1.10754 +#: ../en/ch10-hook.xml:454
 1.10755 +msgid ""
 1.10756 +"When you are writing a hook, you might find it useful to run Mercurial either "
 1.10757 +"with the <option role=\"hg-opt-global\">-v</option> option, or the <envar "
 1.10758 +"role=\"rc-item-ui\">verbose</envar> config item set to <quote>true</quote>.  "
 1.10759 +"When you do so, Mercurial will print a message before it calls each hook."
 1.10760 +msgstr ""
 1.10761 +
 1.10762 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10763 +#: ../en/ch10-hook.xml:463
 1.10764 +msgid "Choosing how your hook should run"
 1.10765 +msgstr ""
 1.10766 +
 1.10767 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10768 +#: ../en/ch10-hook.xml:465
 1.10769 +msgid ""
 1.10770 +"You can write a hook either as a normal program&emdash;typically a shell "
 1.10771 +"script&emdash;or as a Python function that is executed within the Mercurial "
 1.10772 +"process."
 1.10773 +msgstr ""
 1.10774 +
 1.10775 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10776 +#: ../en/ch10-hook.xml:470
 1.10777 +msgid ""
 1.10778 +"Writing a hook as an external program has the advantage that it requires no "
 1.10779 +"knowledge of Mercurial's internals.  You can call normal Mercurial commands "
 1.10780 +"to get any added information you need.  The trade-off is that external hooks "
 1.10781 +"are slower than in-process hooks."
 1.10782 +msgstr ""
 1.10783 +
 1.10784 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10785 +#: ../en/ch10-hook.xml:477
 1.10786 +msgid ""
 1.10787 +"An in-process Python hook has complete access to the Mercurial API, and does "
 1.10788 +"not <quote>shell out</quote> to another process, so it is inherently faster "
 1.10789 +"than an external hook.  It is also easier to obtain much of the information "
 1.10790 +"that a hook requires by using the Mercurial API than by running Mercurial "
 1.10791 +"commands."
 1.10792 +msgstr ""
 1.10793 +
 1.10794 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10795 +#: ../en/ch10-hook.xml:485
 1.10796 +msgid ""
 1.10797 +"If you are comfortable with Python, or require high performance, writing your "
 1.10798 +"hooks in Python may be a good choice.  However, when you have a "
 1.10799 +"straightforward hook to write and you don't need to care about performance "
 1.10800 +"(probably the majority of hooks), a shell script is perfectly fine."
 1.10801 +msgstr ""
 1.10802 +
 1.10803 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10804 +#: ../en/ch10-hook.xml:494
 1.10805 +msgid "Hook parameters"
 1.10806 +msgstr ""
 1.10807 +
 1.10808 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10809 +#: ../en/ch10-hook.xml:496
 1.10810 +msgid ""
 1.10811 +"Mercurial calls each hook with a set of well-defined parameters.  In Python, "
 1.10812 +"a parameter is passed as a keyword argument to your hook function.  For an "
 1.10813 +"external program, a parameter is passed as an environment variable."
 1.10814 +msgstr ""
 1.10815 +
 1.10816 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10817 +#: ../en/ch10-hook.xml:502
 1.10818 +msgid ""
 1.10819 +"Whether your hook is written in Python or as a shell script, the hook-"
 1.10820 +"specific parameter names and values will be the same.  A boolean parameter "
 1.10821 +"will be represented as a boolean value in Python, but as the number 1 (for "
 1.10822 +"<quote>true</quote>) or 0 (for <quote>false</quote>) as an environment "
 1.10823 +"variable for an external hook.  If a hook parameter is named <literal>foo</"
 1.10824 +"literal>, the keyword argument for a Python hook will also be named "
 1.10825 +"<literal>foo</literal>, while the environment variable for an external hook "
 1.10826 +"will be named <literal>HG_FOO</literal>."
 1.10827 +msgstr ""
 1.10828 +
 1.10829 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10830 +#: ../en/ch10-hook.xml:516
 1.10831 +msgid "Hook return values and activity control"
 1.10832 +msgstr ""
 1.10833 +
 1.10834 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10835 +#: ../en/ch10-hook.xml:518
 1.10836 +msgid ""
 1.10837 +"A hook that executes successfully must exit with a status of zero if "
 1.10838 +"external, or return boolean <quote>false</quote> if in-process.  Failure is "
 1.10839 +"indicated with a non-zero exit status from an external hook, or an in-process "
 1.10840 +"hook returning boolean <quote>true</quote>.  If an in-process hook raises an "
 1.10841 +"exception, the hook is considered to have failed."
 1.10842 +msgstr ""
 1.10843 +
 1.10844 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10845 +#: ../en/ch10-hook.xml:526
 1.10846 +msgid ""
 1.10847 +"For a hook that controls whether an activity can proceed, zero/false means "
 1.10848 +"<quote>allow</quote>, while non-zero/true/exception means <quote>deny</quote>."
 1.10849 +msgstr ""
 1.10850 +
 1.10851 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10852 +#: ../en/ch10-hook.xml:533
 1.10853 +msgid "Writing an external hook"
 1.10854 +msgstr ""
 1.10855 +
 1.10856 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10857 +#: ../en/ch10-hook.xml:535
 1.10858 +msgid ""
 1.10859 +"When you define an external hook in your <filename role=\"special\"> /.hgrc</"
 1.10860 +"filename>\\ and the hook is run, its value is passed to your shell, which "
 1.10861 +"interprets it.  This means that you can use normal shell constructs in the "
 1.10862 +"body of the hook."
 1.10863 +msgstr ""
 1.10864 +
 1.10865 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10866 +#: ../en/ch10-hook.xml:542
 1.10867 +msgid ""
 1.10868 +"An executable hook is always run with its current directory set to a "
 1.10869 +"repository's root directory."
 1.10870 +msgstr ""
 1.10871 +
 1.10872 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10873 +#: ../en/ch10-hook.xml:546
 1.10874 +msgid ""
 1.10875 +"Each hook parameter is passed in as an environment variable; the name is "
 1.10876 +"upper-cased, and prefixed with the string <quote><literal>HG_</literal></"
 1.10877 +"quote>."
 1.10878 +msgstr ""
 1.10879 +
 1.10880 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10881 +#: ../en/ch10-hook.xml:551
 1.10882 +msgid ""
 1.10883 +"With the exception of hook parameters, Mercurial does not set or modify any "
 1.10884 +"environment variables when running a hook.  This is useful to remember if you "
 1.10885 +"are writing a site-wide hook that may be run by a number of different users "
 1.10886 +"with differing environment variables set. In multi-user situations, you "
 1.10887 +"should not rely on environment variables being set to the values you have in "
 1.10888 +"your environment when testing the hook."
 1.10889 +msgstr ""
 1.10890 +
 1.10891 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10892 +#: ../en/ch10-hook.xml:562
 1.10893 +msgid "Telling Mercurial to use an in-process hook"
 1.10894 +msgstr ""
 1.10895 +
 1.10896 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10897 +#: ../en/ch10-hook.xml:564
 1.10898 +msgid ""
 1.10899 +"The <filename role=\"special\"> /.hgrc</filename>\\ syntax for defining an in-"
 1.10900 +"process hook is slightly different than for an executable hook.  The value of "
 1.10901 +"the hook must start with the text <quote><literal>python:</literal></quote>, "
 1.10902 +"and continue with the fully-qualified name of a callable object to use as the "
 1.10903 +"hook's value."
 1.10904 +msgstr ""
 1.10905 +
 1.10906 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10907 +#: ../en/ch10-hook.xml:572
 1.10908 +msgid ""
 1.10909 +"The module in which a hook lives is automatically imported when a hook is "
 1.10910 +"run.  So long as you have the module name and <envar>PYTHONPATH</envar> "
 1.10911 +"right, it should <quote>just work</quote>."
 1.10912 +msgstr ""
 1.10913 +
 1.10914 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10915 +#: ../en/ch10-hook.xml:578
 1.10916 +msgid ""
 1.10917 +"The following <filename role=\"special\"> /.hgrc</filename>\\ example snippet "
 1.10918 +"illustrates the syntax and meaning of the notions we just described."
 1.10919 +msgstr ""
 1.10920 +
 1.10921 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10922 +#: ../en/ch10-hook.xml:584
 1.10923 +msgid ""
 1.10924 +"When Mercurial runs the <literal>commit.example</literal> hook, it imports "
 1.10925 +"<literal>mymodule.submodule</literal>, looks for the callable object named "
 1.10926 +"<literal>myhook</literal>, and calls it."
 1.10927 +msgstr ""
 1.10928 +
 1.10929 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10930 +#: ../en/ch10-hook.xml:592
 1.10931 +msgid "Writing an in-process hook"
 1.10932 +msgstr ""
 1.10933 +
 1.10934 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10935 +#: ../en/ch10-hook.xml:594
 1.10936 +msgid ""
 1.10937 +"The simplest in-process hook does nothing, but illustrates the basic shape of "
 1.10938 +"the hook API:"
 1.10939 +msgstr ""
 1.10940 +
 1.10941 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10942 +#: ../en/ch10-hook.xml:599
 1.10943 +msgid ""
 1.10944 +"The first argument to a Python hook is always a <literal role=\"py-mod-"
 1.10945 +"mercurial.ui\">ui</literal> object.  The second is a repository object; at "
 1.10946 +"the moment, it is always an instance of <literal role=\"py-mod-mercurial."
 1.10947 +"localrepo\">localrepository</literal>.  Following these two arguments are "
 1.10948 +"other keyword arguments.  Which ones are passed in depends on the hook being "
 1.10949 +"called, but a hook can ignore arguments it doesn't care about by dropping "
 1.10950 +"them into a keyword argument dict, as with <literal>**kwargs</literal> above."
 1.10951 +msgstr ""
 1.10952 +
 1.10953 +#. type: Content of: <book><chapter><sect1><title>
 1.10954 +#: ../en/ch10-hook.xml:614
 1.10955 +msgid "Some hook examples"
 1.10956 +msgstr ""
 1.10957 +
 1.10958 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10959 +#: ../en/ch10-hook.xml:617
 1.10960 +msgid "Writing meaningful commit messages"
 1.10961 +msgstr ""
 1.10962 +
 1.10963 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10964 +#: ../en/ch10-hook.xml:619
 1.10965 +msgid ""
 1.10966 +"It's hard to imagine a useful commit message being very short. The simple "
 1.10967 +"<literal role=\"hook\">pretxncommit</literal> hook of the example below will "
 1.10968 +"prevent you from committing a changeset with a message that is less than ten "
 1.10969 +"bytes long."
 1.10970 +msgstr ""
 1.10971 +
 1.10972 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.10973 +#: ../en/ch10-hook.xml:629
 1.10974 +msgid "Checking for trailing whitespace"
 1.10975 +msgstr ""
 1.10976 +
 1.10977 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10978 +#: ../en/ch10-hook.xml:631
 1.10979 +msgid ""
 1.10980 +"An interesting use of a commit-related hook is to help you to write cleaner "
 1.10981 +"code.  A simple example of <quote>cleaner code</quote> is the dictum that a "
 1.10982 +"change should not add any new lines of text that contain <quote>trailing "
 1.10983 +"whitespace</quote>.  Trailing whitespace is a series of space and tab "
 1.10984 +"characters at the end of a line of text.  In most cases, trailing whitespace "
 1.10985 +"is unnecessary, invisible noise, but it is occasionally problematic, and "
 1.10986 +"people often prefer to get rid of it."
 1.10987 +msgstr ""
 1.10988 +
 1.10989 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.10990 +#: ../en/ch10-hook.xml:642
 1.10991 +msgid ""
 1.10992 +"You can use either the <literal role=\"hook\">precommit</literal> or <literal "
 1.10993 +"role=\"hook\">pretxncommit</literal> hook to tell whether you have a trailing "
 1.10994 +"whitespace problem.  If you use the <literal role=\"hook\">precommit</"
 1.10995 +"literal> hook, the hook will not know which files you are committing, so it "
 1.10996 +"will have to check every modified file in the repository for trailing white "
 1.10997 +"space.  If you want to commit a change to just the file <filename>foo</"
 1.10998 +"filename>, but the file <filename>bar</filename> contains trailing "
 1.10999 +"whitespace, doing a check in the <literal role=\"hook\">precommit</literal> "
 1.11000 +"hook will prevent you from committing <filename>foo</filename> due to the "
 1.11001 +"problem with <filename>bar</filename>.  This doesn't seem right."
 1.11002 +msgstr ""
 1.11003 +
 1.11004 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11005 +#: ../en/ch10-hook.xml:658
 1.11006 +msgid ""
 1.11007 +"Should you choose the <literal role=\"hook\">pretxncommit</literal> hook, the "
 1.11008 +"check won't occur until just before the transaction for the commit "
 1.11009 +"completes.  This will allow you to check for problems only the exact files "
 1.11010 +"that are being committed.  However, if you entered the commit message "
 1.11011 +"interactively and the hook fails, the transaction will roll back; you'll have "
 1.11012 +"to re-enter the commit message after you fix the trailing whitespace and run "
 1.11013 +"<command role=\"hg-cmd\">hg commit</command> again."
 1.11014 +msgstr ""
 1.11015 +
 1.11016 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11017 +#: ../en/ch10-hook.xml:671
 1.11018 +msgid ""
 1.11019 +"In this example, we introduce a simple <literal role=\"hook\">pretxncommit</"
 1.11020 +"literal> hook that checks for trailing whitespace.  This hook is short, but "
 1.11021 +"not very helpful.  It exits with an error status if a change adds a line with "
 1.11022 +"trailing whitespace to any file, but does not print any information that "
 1.11023 +"might help us to identify the offending file or line.  It also has the nice "
 1.11024 +"property of not paying attention to unmodified lines; only lines that "
 1.11025 +"introduce new trailing whitespace cause problems."
 1.11026 +msgstr ""
 1.11027 +
 1.11028 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11029 +#: ../en/ch10-hook.xml:682
 1.11030 +msgid ""
 1.11031 +"The above version is much more complex, but also more useful.  It parses a "
 1.11032 +"unified diff to see if any lines add trailing whitespace, and prints the name "
 1.11033 +"of the file and the line number of each such occurrence.  Even better, if the "
 1.11034 +"change adds trailing whitespace, this hook saves the commit comment and "
 1.11035 +"prints the name of the save file before exiting and telling Mercurial to roll "
 1.11036 +"the transaction back, so you can use the <option role=\"hg-opt-commit\">-l "
 1.11037 +"filename</option> option to <command role=\"hg-cmd\">hg commit</command> to "
 1.11038 +"reuse the saved commit message once you've corrected the problem."
 1.11039 +msgstr ""
 1.11040 +
 1.11041 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11042 +#: ../en/ch10-hook.xml:696
 1.11043 +msgid ""
 1.11044 +"As a final aside, note in the example above the use of <command>perl</"
 1.11045 +"command>'s in-place editing feature to get rid of trailing whitespace from a "
 1.11046 +"file.  This is concise and useful enough that I will reproduce it here."
 1.11047 +msgstr ""
 1.11048 +
 1.11049 +#. type: Content of: <book><chapter><sect1><title>
 1.11050 +#: ../en/ch10-hook.xml:706
 1.11051 +msgid "Bundled hooks"
 1.11052 +msgstr ""
 1.11053 +
 1.11054 +#. type: Content of: <book><chapter><sect1><para>
 1.11055 +#: ../en/ch10-hook.xml:708
 1.11056 +msgid ""
 1.11057 +"Mercurial ships with several bundled hooks.  You can find them in the "
 1.11058 +"<filename class=\"directory\">hgext</filename> directory of a Mercurial "
 1.11059 +"source tree.  If you are using a Mercurial binary package, the hooks will be "
 1.11060 +"located in the <filename class=\"directory\">hgext</filename> directory of "
 1.11061 +"wherever your package installer put Mercurial."
 1.11062 +msgstr ""
 1.11063 +
 1.11064 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11065 +#: ../en/ch10-hook.xml:717
 1.11066 +msgid ""
 1.11067 +"<literal role=\"hg-ext\">acl</literal>&emdash;access control for parts of a "
 1.11068 +"repository"
 1.11069 +msgstr ""
 1.11070 +
 1.11071 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11072 +#: ../en/ch10-hook.xml:720
 1.11073 +msgid ""
 1.11074 +"The <literal role=\"hg-ext\">acl</literal> extension lets you control which "
 1.11075 +"remote users are allowed to push changesets to a networked server.  You can "
 1.11076 +"protect any portion of a repository (including the entire repo), so that a "
 1.11077 +"specific remote user can push changes that do not affect the protected "
 1.11078 +"portion."
 1.11079 +msgstr ""
 1.11080 +
 1.11081 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11082 +#: ../en/ch10-hook.xml:728
 1.11083 +msgid ""
 1.11084 +"This extension implements access control based on the identity of the user "
 1.11085 +"performing a push, <emphasis>not</emphasis> on who committed the changesets "
 1.11086 +"they're pushing.  It makes sense to use this hook only if you have a locked-"
 1.11087 +"down server environment that authenticates remote users, and you want to be "
 1.11088 +"sure that only specific users are allowed to push changes to that server."
 1.11089 +msgstr ""
 1.11090 +
 1.11091 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11092 +#: ../en/ch10-hook.xml:738
 1.11093 +msgid "Configuring the <literal role=\"hook\">acl</literal> hook"
 1.11094 +msgstr ""
 1.11095 +
 1.11096 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11097 +#: ../en/ch10-hook.xml:741
 1.11098 +msgid ""
 1.11099 +"In order to manage incoming changesets, the <literal role=\"hg-ext\">acl</"
 1.11100 +"literal> hook must be used as a <literal role=\"hook\">pretxnchangegroup</"
 1.11101 +"literal> hook.  This lets it see which files are modified by each incoming "
 1.11102 +"changeset, and roll back a group of changesets if they modify "
 1.11103 +"<quote>forbidden</quote> files.  Example:"
 1.11104 +msgstr ""
 1.11105 +
 1.11106 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11107 +#: ../en/ch10-hook.xml:751
 1.11108 +msgid ""
 1.11109 +"The <literal role=\"hg-ext\">acl</literal> extension is configured using "
 1.11110 +"three sections."
 1.11111 +msgstr ""
 1.11112 +
 1.11113 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11114 +#: ../en/ch10-hook.xml:755
 1.11115 +msgid ""
 1.11116 +"The <literal role=\"rc-acl\">acl</literal> section has only one entry, <envar "
 1.11117 +"role=\"rc-item-acl\">sources</envar>, which lists the sources of incoming "
 1.11118 +"changesets that the hook should pay attention to.  You don't normally need to "
 1.11119 +"configure this section."
 1.11120 +msgstr ""
 1.11121 +
 1.11122 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11123 +#: ../en/ch10-hook.xml:762
 1.11124 +msgid ""
 1.11125 +"<envar role=\"rc-item-acl\">serve</envar>: Control incoming changesets that "
 1.11126 +"are arriving from a remote repository over http or ssh.  This is the default "
 1.11127 +"value of <envar role=\"rc-item-acl\">sources</envar>, and usually the only "
 1.11128 +"setting you'll need for this configuration item."
 1.11129 +msgstr ""
 1.11130 +
 1.11131 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11132 +#: ../en/ch10-hook.xml:770
 1.11133 +msgid ""
 1.11134 +"<envar role=\"rc-item-acl\">pull</envar>: Control incoming changesets that "
 1.11135 +"are arriving via a pull from a local repository."
 1.11136 +msgstr ""
 1.11137 +
 1.11138 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11139 +#: ../en/ch10-hook.xml:775
 1.11140 +msgid ""
 1.11141 +"<envar role=\"rc-item-acl\">push</envar>: Control incoming changesets that "
 1.11142 +"are arriving via a push from a local repository."
 1.11143 +msgstr ""
 1.11144 +
 1.11145 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11146 +#: ../en/ch10-hook.xml:780
 1.11147 +msgid ""
 1.11148 +"<envar role=\"rc-item-acl\">bundle</envar>: Control incoming changesets that "
 1.11149 +"are arriving from another repository via a bundle."
 1.11150 +msgstr ""
 1.11151 +
 1.11152 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11153 +#: ../en/ch10-hook.xml:786
 1.11154 +msgid ""
 1.11155 +"The <literal role=\"rc-acl.allow\">acl.allow</literal> section controls the "
 1.11156 +"users that are allowed to add changesets to the repository.  If this section "
 1.11157 +"is not present, all users that are not explicitly denied are allowed.  If "
 1.11158 +"this section is present, all users that are not explicitly allowed are denied "
 1.11159 +"(so an empty section means that all users are denied)."
 1.11160 +msgstr ""
 1.11161 +
 1.11162 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11163 +#: ../en/ch10-hook.xml:795
 1.11164 +msgid ""
 1.11165 +"The <literal role=\"rc-acl.deny\">acl.deny</literal> section determines which "
 1.11166 +"users are denied from adding changesets to the repository.  If this section "
 1.11167 +"is not present or is empty, no users are denied."
 1.11168 +msgstr ""
 1.11169 +
 1.11170 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11171 +#: ../en/ch10-hook.xml:801
 1.11172 +msgid ""
 1.11173 +"The syntaxes for the <literal role=\"rc-acl.allow\">acl.allow</literal> and "
 1.11174 +"<literal role=\"rc-acl.deny\">acl.deny</literal> sections are identical.  On "
 1.11175 +"the left of each entry is a glob pattern that matches files or directories, "
 1.11176 +"relative to the root of the repository; on the right, a user name."
 1.11177 +msgstr ""
 1.11178 +
 1.11179 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11180 +#: ../en/ch10-hook.xml:809
 1.11181 +msgid ""
 1.11182 +"In the following example, the user <literal>docwriter</literal> can only push "
 1.11183 +"changes to the <filename class=\"directory\">docs</filename> subtree of the "
 1.11184 +"repository, while <literal>intern</literal> can push changes to any file or "
 1.11185 +"directory except <filename class=\"directory\">source/sensitive</filename>."
 1.11186 +msgstr ""
 1.11187 +
 1.11188 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11189 +#: ../en/ch10-hook.xml:821 ../en/ch10-hook.xml:1095 ../en/ch10-hook.xml:1308
 1.11190 +msgid "Testing and troubleshooting"
 1.11191 +msgstr ""
 1.11192 +
 1.11193 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11194 +#: ../en/ch10-hook.xml:823
 1.11195 +msgid ""
 1.11196 +"If you want to test the <literal role=\"hg-ext\">acl</literal> hook, run it "
 1.11197 +"with Mercurial's debugging output enabled.  Since you'll probably be running "
 1.11198 +"it on a server where it's not convenient (or sometimes possible) to pass in "
 1.11199 +"the <option role=\"hg-opt-global\">--debug</option> option, don't forget that "
 1.11200 +"you can enable debugging output in your <filename role=\"special\"> /.hgrc</"
 1.11201 +"filename>:"
 1.11202 +msgstr ""
 1.11203 +
 1.11204 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11205 +#: ../en/ch10-hook.xml:833
 1.11206 +msgid ""
 1.11207 +"With this enabled, the <literal role=\"hg-ext\">acl</literal> hook will print "
 1.11208 +"enough information to let you figure out why it is allowing or forbidding "
 1.11209 +"pushes from specific users."
 1.11210 +msgstr ""
 1.11211 +
 1.11212 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11213 +#: ../en/ch10-hook.xml:842
 1.11214 +msgid ""
 1.11215 +"<literal role=\"hg-ext\">bugzilla</literal>&emdash;integration with Bugzilla"
 1.11216 +msgstr ""
 1.11217 +
 1.11218 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11219 +#: ../en/ch10-hook.xml:846
 1.11220 +msgid ""
 1.11221 +"The <literal role=\"hg-ext\">bugzilla</literal> extension adds a comment to a "
 1.11222 +"Bugzilla bug whenever it finds a reference to that bug ID in a commit "
 1.11223 +"comment.  You can install this hook on a shared server, so that any time a "
 1.11224 +"remote user pushes changes to this server, the hook gets run."
 1.11225 +msgstr ""
 1.11226 +
 1.11227 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11228 +#: ../en/ch10-hook.xml:853
 1.11229 +msgid ""
 1.11230 +"It adds a comment to the bug that looks like this (you can configure the "
 1.11231 +"contents of the comment&emdash;see below):"
 1.11232 +msgstr ""
 1.11233 +
 1.11234 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11235 +#: ../en/ch10-hook.xml:862
 1.11236 +msgid ""
 1.11237 +"The value of this hook is that it automates the process of updating a bug any "
 1.11238 +"time a changeset refers to it.  If you configure the hook properly, it makes "
 1.11239 +"it easy for people to browse straight from a Bugzilla bug to a changeset that "
 1.11240 +"refers to that bug."
 1.11241 +msgstr ""
 1.11242 +
 1.11243 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11244 +#: ../en/ch10-hook.xml:869
 1.11245 +msgid ""
 1.11246 +"You can use the code in this hook as a starting point for some more exotic "
 1.11247 +"Bugzilla integration recipes.  Here are a few possibilities:"
 1.11248 +msgstr ""
 1.11249 +
 1.11250 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11251 +#: ../en/ch10-hook.xml:874
 1.11252 +msgid ""
 1.11253 +"Require that every changeset pushed to the server have a valid bug ID in its "
 1.11254 +"commit comment.  In this case, you'd want to configure the hook as a <literal "
 1.11255 +"role=\"hook\">pretxncommit</literal> hook.  This would allow the hook to "
 1.11256 +"reject changes that didn't contain bug IDs."
 1.11257 +msgstr ""
 1.11258 +
 1.11259 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11260 +#: ../en/ch10-hook.xml:882
 1.11261 +msgid ""
 1.11262 +"Allow incoming changesets to automatically modify the <emphasis>state</"
 1.11263 +"emphasis> of a bug, as well as simply adding a comment.  For example, the "
 1.11264 +"hook could recognise the string <quote>fixed bug 31337</quote> as indicating "
 1.11265 +"that it should update the state of bug 31337 to <quote>requires testing</"
 1.11266 +"quote>."
 1.11267 +msgstr ""
 1.11268 +
 1.11269 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11270 +#: ../en/ch10-hook.xml:892
 1.11271 +msgid "Configuring the <literal role=\"hook\">bugzilla</literal> hook"
 1.11272 +msgstr ""
 1.11273 +
 1.11274 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11275 +#: ../en/ch10-hook.xml:895
 1.11276 +msgid ""
 1.11277 +"You should configure this hook in your server's <filename role=\"special\"> /."
 1.11278 +"hgrc</filename>\\ as an <literal role=\"hook\">incoming</literal> hook, for "
 1.11279 +"example as follows:"
 1.11280 +msgstr ""
 1.11281 +
 1.11282 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11283 +#: ../en/ch10-hook.xml:903
 1.11284 +msgid ""
 1.11285 +"Because of the specialised nature of this hook, and because Bugzilla was not "
 1.11286 +"written with this kind of integration in mind, configuring this hook is a "
 1.11287 +"somewhat involved process."
 1.11288 +msgstr ""
 1.11289 +
 1.11290 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11291 +#: ../en/ch10-hook.xml:909
 1.11292 +msgid ""
 1.11293 +"Before you begin, you must install the MySQL bindings for Python on the host"
 1.11294 +"(s) where you'll be running the hook.  If this is not available as a binary "
 1.11295 +"package for your system, you can download it from <citation>web:mysql-python</"
 1.11296 +"citation>."
 1.11297 +msgstr ""
 1.11298 +
 1.11299 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11300 +#: ../en/ch10-hook.xml:916
 1.11301 +msgid ""
 1.11302 +"Configuration information for this hook lives in the <literal role=\"rc-"
 1.11303 +"bugzilla\">bugzilla</literal> section of your <filename role=\"special\"> /."
 1.11304 +"hgrc</filename>."
 1.11305 +msgstr ""
 1.11306 +
 1.11307 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11308 +#: ../en/ch10-hook.xml:921
 1.11309 +msgid ""
 1.11310 +"<envar role=\"rc-item-bugzilla\">version</envar>: The version of Bugzilla "
 1.11311 +"installed on the server.  The database schema that Bugzilla uses changes "
 1.11312 +"occasionally, so this hook has to know exactly which schema to use. At the "
 1.11313 +"moment, the only version supported is <literal>2.16</literal>."
 1.11314 +msgstr ""
 1.11315 +
 1.11316 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11317 +#: ../en/ch10-hook.xml:930
 1.11318 +msgid ""
 1.11319 +"<envar role=\"rc-item-bugzilla\">host</envar>: The hostname of the MySQL "
 1.11320 +"server that stores your Bugzilla data.  The database must be configured to "
 1.11321 +"allow connections from whatever host you are running the <literal role=\"hook"
 1.11322 +"\">bugzilla</literal> hook on."
 1.11323 +msgstr ""
 1.11324 +
 1.11325 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11326 +#: ../en/ch10-hook.xml:937
 1.11327 +msgid ""
 1.11328 +"<envar role=\"rc-item-bugzilla\">user</envar>: The username with which to "
 1.11329 +"connect to the MySQL server.  The database must be configured to allow this "
 1.11330 +"user to connect from whatever host you are running the <literal role=\"hook"
 1.11331 +"\">bugzilla</literal> hook on.  This user must be able to access and modify "
 1.11332 +"Bugzilla tables.  The default value of this item is <literal>bugs</literal>, "
 1.11333 +"which is the standard name of the Bugzilla user in a MySQL database."
 1.11334 +msgstr ""
 1.11335 +
 1.11336 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11337 +#: ../en/ch10-hook.xml:948
 1.11338 +msgid ""
 1.11339 +"<envar role=\"rc-item-bugzilla\">password</envar>: The MySQL password for the "
 1.11340 +"user you configured above.  This is stored as plain text, so you should make "
 1.11341 +"sure that unauthorised users cannot read the <filename role=\"special\"> /."
 1.11342 +"hgrc</filename>\\ file where you store this information."
 1.11343 +msgstr ""
 1.11344 +
 1.11345 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11346 +#: ../en/ch10-hook.xml:957
 1.11347 +msgid ""
 1.11348 +"<envar role=\"rc-item-bugzilla\">db</envar>: The name of the Bugzilla "
 1.11349 +"database on the MySQL server.  The default value of this item is "
 1.11350 +"<literal>bugs</literal>, which is the standard name of the MySQL database "
 1.11351 +"where Bugzilla stores its data."
 1.11352 +msgstr ""
 1.11353 +
 1.11354 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11355 +#: ../en/ch10-hook.xml:964
 1.11356 +msgid ""
 1.11357 +"<envar role=\"rc-item-bugzilla\">notify</envar>: If you want Bugzilla to send "
 1.11358 +"out a notification email to subscribers after this hook has added a comment "
 1.11359 +"to a bug, you will need this hook to run a command whenever it updates the "
 1.11360 +"database.  The command to run depends on where you have installed Bugzilla, "
 1.11361 +"but it will typically look something like this, if you have Bugzilla "
 1.11362 +"installed in <filename class=\"directory\">/var/www/html/bugzilla</filename>:"
 1.11363 +msgstr ""
 1.11364 +
 1.11365 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11366 +#: ../en/ch10-hook.xml:977
 1.11367 +msgid ""
 1.11368 +"The Bugzilla <literal>processmail</literal> program expects to be given a bug "
 1.11369 +"ID (the hook replaces <quote><literal>%s</literal></quote> with the bug ID)  "
 1.11370 +"and an email address.  It also expects to be able to write to some files in "
 1.11371 +"the directory that it runs in.  If Bugzilla and this hook are not installed "
 1.11372 +"on the same machine, you will need to find a way to run <literal>processmail</"
 1.11373 +"literal> on the server where Bugzilla is installed."
 1.11374 +msgstr ""
 1.11375 +
 1.11376 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11377 +#: ../en/ch10-hook.xml:992
 1.11378 +msgid "Mapping committer names to Bugzilla user names"
 1.11379 +msgstr ""
 1.11380 +
 1.11381 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11382 +#: ../en/ch10-hook.xml:994
 1.11383 +msgid ""
 1.11384 +"By default, the <literal role=\"hg-ext\">bugzilla</literal> hook tries to use "
 1.11385 +"the email address of a changeset's committer as the Bugzilla user name with "
 1.11386 +"which to update a bug.  If this does not suit your needs, you can map "
 1.11387 +"committer email addresses to Bugzilla user names using a <literal role=\"rc-"
 1.11388 +"usermap\">usermap</literal> section."
 1.11389 +msgstr ""
 1.11390 +
 1.11391 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11392 +#: ../en/ch10-hook.xml:1003
 1.11393 +msgid ""
 1.11394 +"Each item in the <literal role=\"rc-usermap\">usermap</literal> section "
 1.11395 +"contains an email address on the left, and a Bugzilla user name on the right."
 1.11396 +msgstr ""
 1.11397 +
 1.11398 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11399 +#: ../en/ch10-hook.xml:1010
 1.11400 +msgid ""
 1.11401 +"You can either keep the <literal role=\"rc-usermap\">usermap</literal> data "
 1.11402 +"in a normal <filename role=\"special\">~/.hgrc</filename>, or tell the "
 1.11403 +"<literal role=\"hg-ext\">bugzilla</literal> hook to read the information from "
 1.11404 +"an external <filename>usermap</filename> file.  In the latter case, you can "
 1.11405 +"store <filename>usermap</filename> data by itself in (for example)  a user-"
 1.11406 +"modifiable repository.  This makes it possible to let your users maintain "
 1.11407 +"their own <envar role=\"rc-item-bugzilla\">usermap</envar> entries.  The main "
 1.11408 +"<filename role=\"special\"> /.hgrc</filename>\\ file might look like this:"
 1.11409 +msgstr ""
 1.11410 +
 1.11411 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11412 +#: ../en/ch10-hook.xml:1026
 1.11413 +msgid ""
 1.11414 +"While the <filename>usermap</filename> file that it refers to might look like "
 1.11415 +"this:"
 1.11416 +msgstr ""
 1.11417 +
 1.11418 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11419 +#: ../en/ch10-hook.xml:1035
 1.11420 +msgid "Configuring the text that gets added to a bug"
 1.11421 +msgstr ""
 1.11422 +
 1.11423 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11424 +#: ../en/ch10-hook.xml:1037
 1.11425 +msgid ""
 1.11426 +"You can configure the text that this hook adds as a comment; you specify it "
 1.11427 +"in the form of a Mercurial template.  Several <filename role=\"special\"> /."
 1.11428 +"hgrc</filename>\\ entries (still in the <literal role=\"rc-bugzilla"
 1.11429 +"\">bugzilla</literal> section) control this behaviour."
 1.11430 +msgstr ""
 1.11431 +
 1.11432 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11433 +#: ../en/ch10-hook.xml:1044
 1.11434 +msgid ""
 1.11435 +"<literal>strip</literal>: The number of leading path elements to strip from a "
 1.11436 +"repository's path name to construct a partial path for a URL. For example, if "
 1.11437 +"the repositories on your server live under <filename class=\"directory\">/"
 1.11438 +"home/hg/repos</filename>, and you have a repository whose path is <filename "
 1.11439 +"class=\"directory\">/home/hg/repos/app/tests</filename>, then setting "
 1.11440 +"<literal>strip</literal> to <literal>4</literal> will give a partial path of "
 1.11441 +"<filename class=\"directory\">app/tests</filename>.  The hook will make this "
 1.11442 +"partial path available when expanding a template, as <literal>webroot</"
 1.11443 +"literal>."
 1.11444 +msgstr ""
 1.11445 +
 1.11446 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11447 +#: ../en/ch10-hook.xml:1058
 1.11448 +msgid ""
 1.11449 +"<literal>template</literal>: The text of the template to use.  In addition to "
 1.11450 +"the usual changeset-related variables, this template can use <literal>hgweb</"
 1.11451 +"literal> (the value of the <literal>hgweb</literal> configuration item above) "
 1.11452 +"and <literal>webroot</literal> (the path constructed using <literal>strip</"
 1.11453 +"literal> above)."
 1.11454 +msgstr ""
 1.11455 +
 1.11456 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11457 +#: ../en/ch10-hook.xml:1068
 1.11458 +msgid ""
 1.11459 +"In addition, you can add a <envar role=\"rc-item-web\">baseurl</envar> item "
 1.11460 +"to the <literal role=\"rc-web\">web</literal> section of your <filename role="
 1.11461 +"\"special\"> /.hgrc</filename>.  The <literal role=\"hg-ext\">bugzilla</"
 1.11462 +"literal> hook will make this available when expanding a template, as the base "
 1.11463 +"string to use when constructing a URL that will let users browse from a "
 1.11464 +"Bugzilla comment to view a changeset.  Example:"
 1.11465 +msgstr ""
 1.11466 +
 1.11467 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11468 +#: ../en/ch10-hook.xml:1080
 1.11469 +msgid ""
 1.11470 +"Here is an example set of <literal role=\"hg-ext\">bugzilla</literal> hook "
 1.11471 +"config information."
 1.11472 +msgstr ""
 1.11473 +
 1.11474 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11475 +#: ../en/ch10-hook.xml:1097
 1.11476 +msgid ""
 1.11477 +"The most common problems with configuring the <literal role=\"hg-ext"
 1.11478 +"\">bugzilla</literal> hook relate to running Bugzilla's "
 1.11479 +"<filename>processmail</filename> script and mapping committer names to user "
 1.11480 +"names."
 1.11481 +msgstr ""
 1.11482 +
 1.11483 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11484 +#: ../en/ch10-hook.xml:1103
 1.11485 +msgid ""
 1.11486 +"Recall from section <xref linkend=\"sec.hook.bugzilla.config\"/> above that "
 1.11487 +"the user that runs the Mercurial process on the server is also the one that "
 1.11488 +"will run the <filename>processmail</filename> script.  The "
 1.11489 +"<filename>processmail</filename> script sometimes causes Bugzilla to write to "
 1.11490 +"files in its configuration directory, and Bugzilla's configuration files are "
 1.11491 +"usually owned by the user that your web server runs under."
 1.11492 +msgstr ""
 1.11493 +
 1.11494 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11495 +#: ../en/ch10-hook.xml:1114
 1.11496 +msgid ""
 1.11497 +"You can cause <filename>processmail</filename> to be run with the suitable "
 1.11498 +"user's identity using the <command>sudo</command> command.  Here is an "
 1.11499 +"example entry for a <filename>sudoers</filename> file."
 1.11500 +msgstr ""
 1.11501 +
 1.11502 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11503 +#: ../en/ch10-hook.xml:1122
 1.11504 +msgid ""
 1.11505 +"This allows the <literal>hg_user</literal> user to run a "
 1.11506 +"<filename>processmail-wrapper</filename> program under the identity of "
 1.11507 +"<literal>httpd_user</literal>."
 1.11508 +msgstr ""
 1.11509 +
 1.11510 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11511 +#: ../en/ch10-hook.xml:1127
 1.11512 +msgid ""
 1.11513 +"This indirection through a wrapper script is necessary, because "
 1.11514 +"<filename>processmail</filename> expects to be run with its current directory "
 1.11515 +"set to wherever you installed Bugzilla; you can't specify that kind of "
 1.11516 +"constraint in a <filename>sudoers</filename> file.  The contents of the "
 1.11517 +"wrapper script are simple:"
 1.11518 +msgstr ""
 1.11519 +
 1.11520 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11521 +#: ../en/ch10-hook.xml:1136
 1.11522 +msgid ""
 1.11523 +"It doesn't seem to matter what email address you pass to "
 1.11524 +"<filename>processmail</filename>."
 1.11525 +msgstr ""
 1.11526 +
 1.11527 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11528 +#: ../en/ch10-hook.xml:1140
 1.11529 +msgid ""
 1.11530 +"If your <literal role=\"rc-usermap\">usermap</literal> is not set up "
 1.11531 +"correctly, users will see an error message from the <literal role=\"hg-ext"
 1.11532 +"\">bugzilla</literal> hook when they push changes to the server.  The error "
 1.11533 +"message will look like this:"
 1.11534 +msgstr ""
 1.11535 +
 1.11536 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11537 +#: ../en/ch10-hook.xml:1148
 1.11538 +msgid ""
 1.11539 +"What this means is that the committer's address, <literal>john.q."
 1.11540 +"public@example.com</literal>, is not a valid Bugzilla user name, nor does it "
 1.11541 +"have an entry in your <literal role=\"rc-usermap\">usermap</literal> that "
 1.11542 +"maps it to a valid Bugzilla user name."
 1.11543 +msgstr ""
 1.11544 +
 1.11545 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11546 +#: ../en/ch10-hook.xml:1158
 1.11547 +msgid ""
 1.11548 +"<literal role=\"hg-ext\">notify</literal>&emdash;send email notifications"
 1.11549 +msgstr ""
 1.11550 +
 1.11551 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11552 +#: ../en/ch10-hook.xml:1161
 1.11553 +msgid ""
 1.11554 +"Although Mercurial's built-in web server provides RSS feeds of changes in "
 1.11555 +"every repository, many people prefer to receive change notifications via "
 1.11556 +"email.  The <literal role=\"hg-ext\">notify</literal> hook lets you send out "
 1.11557 +"notifications to a set of email addresses whenever changesets arrive that "
 1.11558 +"those subscribers are interested in."
 1.11559 +msgstr ""
 1.11560 +
 1.11561 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11562 +#: ../en/ch10-hook.xml:1169
 1.11563 +msgid ""
 1.11564 +"As with the <literal role=\"hg-ext\">bugzilla</literal> hook, the <literal "
 1.11565 +"role=\"hg-ext\">notify</literal> hook is template-driven, so you can "
 1.11566 +"customise the contents of the notification messages that it sends."
 1.11567 +msgstr ""
 1.11568 +
 1.11569 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11570 +#: ../en/ch10-hook.xml:1175
 1.11571 +msgid ""
 1.11572 +"By default, the <literal role=\"hg-ext\">notify</literal> hook includes a "
 1.11573 +"diff of every changeset that it sends out; you can limit the size of the "
 1.11574 +"diff, or turn this feature off entirely.  It is useful for letting "
 1.11575 +"subscribers review changes immediately, rather than clicking to follow a URL."
 1.11576 +msgstr ""
 1.11577 +
 1.11578 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11579 +#: ../en/ch10-hook.xml:1183
 1.11580 +msgid "Configuring the <literal role=\"hg-ext\">notify</literal> hook"
 1.11581 +msgstr ""
 1.11582 +
 1.11583 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11584 +#: ../en/ch10-hook.xml:1186
 1.11585 +msgid ""
 1.11586 +"You can set up the <literal role=\"hg-ext\">notify</literal> hook to send one "
 1.11587 +"email message per incoming changeset, or one per incoming group of changesets "
 1.11588 +"(all those that arrived in a single pull or push)."
 1.11589 +msgstr ""
 1.11590 +
 1.11591 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11592 +#: ../en/ch10-hook.xml:1197
 1.11593 +msgid ""
 1.11594 +"Configuration information for this hook lives in the <literal role=\"rc-notify"
 1.11595 +"\">notify</literal> section of a <filename role=\"special\"> /.hgrc</filename>"
 1.11596 +"\\ file."
 1.11597 +msgstr ""
 1.11598 +
 1.11599 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11600 +#: ../en/ch10-hook.xml:1202
 1.11601 +msgid ""
 1.11602 +"<envar role=\"rc-item-notify\">test</envar>: By default, this hook does not "
 1.11603 +"send out email at all; instead, it prints the message that it "
 1.11604 +"<emphasis>would</emphasis> send.  Set this item to <literal>false</literal> "
 1.11605 +"to allow email to be sent. The reason that sending of email is turned off by "
 1.11606 +"default is that it takes several tries to configure this extension exactly as "
 1.11607 +"you would like, and it would be bad form to spam subscribers with a number of "
 1.11608 +"<quote>broken</quote> notifications while you debug your configuration."
 1.11609 +msgstr ""
 1.11610 +
 1.11611 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11612 +#: ../en/ch10-hook.xml:1214
 1.11613 +msgid ""
 1.11614 +"<envar role=\"rc-item-notify\">config</envar>: The path to a configuration "
 1.11615 +"file that contains subscription information.  This is kept separate from the "
 1.11616 +"main <filename role=\"special\"> /.hgrc</filename>\\ so that you can maintain "
 1.11617 +"it in a repository of its own.  People can then clone that repository, update "
 1.11618 +"their subscriptions, and push the changes back to your server."
 1.11619 +msgstr ""
 1.11620 +
 1.11621 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11622 +#: ../en/ch10-hook.xml:1223
 1.11623 +msgid ""
 1.11624 +"<envar role=\"rc-item-notify\">strip</envar>: The number of leading path "
 1.11625 +"separator characters to strip from a repository's path, when deciding whether "
 1.11626 +"a repository has subscribers.  For example, if the repositories on your "
 1.11627 +"server live in <filename class=\"directory\">/home/hg/repos</filename>, and "
 1.11628 +"<literal role=\"hg-ext\">notify</literal> is considering a repository named "
 1.11629 +"<filename class=\"directory\">/home/hg/repos/shared/test</filename>, setting "
 1.11630 +"<envar role=\"rc-item-notify\">strip</envar> to <literal>4</literal> will "
 1.11631 +"cause <literal role=\"hg-ext\">notify</literal> to trim the path it considers "
 1.11632 +"down to <filename class=\"directory\">shared/test</filename>, and it will "
 1.11633 +"match subscribers against that."
 1.11634 +msgstr ""
 1.11635 +
 1.11636 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11637 +#: ../en/ch10-hook.xml:1240
 1.11638 +msgid ""
 1.11639 +"<envar role=\"rc-item-notify\">template</envar>: The template text to use "
 1.11640 +"when sending messages.  This specifies both the contents of the message "
 1.11641 +"header and its body."
 1.11642 +msgstr ""
 1.11643 +
 1.11644 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11645 +#: ../en/ch10-hook.xml:1246
 1.11646 +msgid ""
 1.11647 +"<envar role=\"rc-item-notify\">maxdiff</envar>: The maximum number of lines "
 1.11648 +"of diff data to append to the end of a message.  If a diff is longer than "
 1.11649 +"this, it is truncated.  By default, this is set to 300.  Set this to "
 1.11650 +"<literal>0</literal> to omit diffs from notification emails."
 1.11651 +msgstr ""
 1.11652 +
 1.11653 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11654 +#: ../en/ch10-hook.xml:1255
 1.11655 +msgid ""
 1.11656 +"<envar role=\"rc-item-notify\">sources</envar>: A list of sources of "
 1.11657 +"changesets to consider.  This lets you limit <literal role=\"hg-ext\">notify</"
 1.11658 +"literal> to only sending out email about changes that remote users pushed "
 1.11659 +"into this repository via a server, for example.  See section <xref linkend="
 1.11660 +"\"sec.hook.sources\"/> for the sources you can specify here."
 1.11661 +msgstr ""
 1.11662 +
 1.11663 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11664 +#: ../en/ch10-hook.xml:1267
 1.11665 +msgid ""
 1.11666 +"If you set the <envar role=\"rc-item-web\">baseurl</envar> item in the "
 1.11667 +"<literal role=\"rc-web\">web</literal> section, you can use it in a template; "
 1.11668 +"it will be available as <literal>webroot</literal>."
 1.11669 +msgstr ""
 1.11670 +
 1.11671 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11672 +#: ../en/ch10-hook.xml:1273
 1.11673 +msgid ""
 1.11674 +"Here is an example set of <literal role=\"hg-ext\">notify</literal> "
 1.11675 +"configuration information."
 1.11676 +msgstr ""
 1.11677 +
 1.11678 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11679 +#: ../en/ch10-hook.xml:1289
 1.11680 +msgid "This will produce a message that looks like the following:"
 1.11681 +msgstr ""
 1.11682 +
 1.11683 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11684 +#: ../en/ch10-hook.xml:1310
 1.11685 +msgid ""
 1.11686 +"Do not forget that by default, the <literal role=\"hg-ext\">notify</literal> "
 1.11687 +"extension <emphasis>will not send any mail</emphasis> until you explicitly "
 1.11688 +"configure it to do so, by setting <envar role=\"rc-item-notify\">test</envar> "
 1.11689 +"to <literal>false</literal>.  Until you do that, it simply prints the message "
 1.11690 +"it <emphasis>would</emphasis> send."
 1.11691 +msgstr ""
 1.11692 +
 1.11693 +#. type: Content of: <book><chapter><sect1><title>
 1.11694 +#: ../en/ch10-hook.xml:1322
 1.11695 +msgid "Information for writers of hooks"
 1.11696 +msgstr ""
 1.11697 +
 1.11698 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11699 +#: ../en/ch10-hook.xml:1325
 1.11700 +msgid "In-process hook execution"
 1.11701 +msgstr ""
 1.11702 +
 1.11703 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11704 +#: ../en/ch10-hook.xml:1327
 1.11705 +msgid "An in-process hook is called with arguments of the following form:"
 1.11706 +msgstr ""
 1.11707 +
 1.11708 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11709 +#: ../en/ch10-hook.xml:1333
 1.11710 +msgid ""
 1.11711 +"The <literal>ui</literal> parameter is a <literal role=\"py-mod-mercurial.ui"
 1.11712 +"\">ui</literal> object. The <literal>repo</literal> parameter is a <literal "
 1.11713 +"role=\"py-mod-mercurial.localrepo\">localrepository</literal> object.  The "
 1.11714 +"names and values of the <literal>**kwargs</literal> parameters depend on the "
 1.11715 +"hook being invoked, with the following common features:"
 1.11716 +msgstr ""
 1.11717 +
 1.11718 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11719 +#: ../en/ch10-hook.xml:1342
 1.11720 +msgid ""
 1.11721 +"If a parameter is named <literal>node</literal> or <literal>parentN</"
 1.11722 +"literal>, it will contain a hexadecimal changeset ID. The empty string is "
 1.11723 +"used to represent <quote>null changeset ID</quote> instead of a string of "
 1.11724 +"zeroes."
 1.11725 +msgstr ""
 1.11726 +
 1.11727 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11728 +#: ../en/ch10-hook.xml:1349
 1.11729 +msgid ""
 1.11730 +"If a parameter is named <literal>url</literal>, it will contain the URL of a "
 1.11731 +"remote repository, if that can be determined."
 1.11732 +msgstr ""
 1.11733 +
 1.11734 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11735 +#: ../en/ch10-hook.xml:1354
 1.11736 +msgid ""
 1.11737 +"Boolean-valued parameters are represented as Python <literal>bool</literal> "
 1.11738 +"objects."
 1.11739 +msgstr ""
 1.11740 +
 1.11741 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11742 +#: ../en/ch10-hook.xml:1359
 1.11743 +msgid ""
 1.11744 +"An in-process hook is called without a change to the process's working "
 1.11745 +"directory (unlike external hooks, which are run in the root of the "
 1.11746 +"repository).  It must not change the process's working directory, or it will "
 1.11747 +"cause any calls it makes into the Mercurial API to fail."
 1.11748 +msgstr ""
 1.11749 +
 1.11750 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11751 +#: ../en/ch10-hook.xml:1366
 1.11752 +msgid ""
 1.11753 +"If a hook returns a boolean <quote>false</quote> value, it is considered to "
 1.11754 +"have succeeded.  If it returns a boolean <quote>true</quote> value or raises "
 1.11755 +"an exception, it is considered to have failed.  A useful way to think of the "
 1.11756 +"calling convention is <quote>tell me if you fail</quote>."
 1.11757 +msgstr ""
 1.11758 +
 1.11759 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11760 +#: ../en/ch10-hook.xml:1373
 1.11761 +msgid ""
 1.11762 +"Note that changeset IDs are passed into Python hooks as hexadecimal strings, "
 1.11763 +"not the binary hashes that Mercurial's APIs normally use.  To convert a hash "
 1.11764 +"from hex to binary, use the \\pymodfunc{mercurial.node}{bin} function."
 1.11765 +msgstr ""
 1.11766 +
 1.11767 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11768 +#: ../en/ch10-hook.xml:1381
 1.11769 +msgid "External hook execution"
 1.11770 +msgstr ""
 1.11771 +
 1.11772 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11773 +#: ../en/ch10-hook.xml:1383
 1.11774 +msgid ""
 1.11775 +"An external hook is passed to the shell of the user running Mercurial. "
 1.11776 +"Features of that shell, such as variable substitution and command "
 1.11777 +"redirection, are available.  The hook is run in the root directory of the "
 1.11778 +"repository (unlike in-process hooks, which are run in the same directory that "
 1.11779 +"Mercurial was run in)."
 1.11780 +msgstr ""
 1.11781 +
 1.11782 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11783 +#: ../en/ch10-hook.xml:1391
 1.11784 +msgid ""
 1.11785 +"Hook parameters are passed to the hook as environment variables.  Each "
 1.11786 +"environment variable's name is converted in upper case and prefixed with the "
 1.11787 +"string <quote><literal>HG_</literal></quote>.  For example, if the name of a "
 1.11788 +"parameter is <quote><literal>node</literal></quote>, the name of the "
 1.11789 +"environment variable representing that parameter will be "
 1.11790 +"<quote><literal>HG_NODE</literal></quote>."
 1.11791 +msgstr ""
 1.11792 +
 1.11793 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11794 +#: ../en/ch10-hook.xml:1400
 1.11795 +msgid ""
 1.11796 +"A boolean parameter is represented as the string <quote><literal>1</literal></"
 1.11797 +"quote> for <quote>true</quote>, <quote><literal>0</literal></quote> for "
 1.11798 +"<quote>false</quote>.  If an environment variable is named <envar>HG_NODE</"
 1.11799 +"envar>, <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it contains a "
 1.11800 +"changeset ID represented as a hexadecimal string.  The empty string is used "
 1.11801 +"to represent <quote>null changeset ID</quote> instead of a string of zeroes.  "
 1.11802 +"If an environment variable is named <envar>HG_URL</envar>, it will contain "
 1.11803 +"the URL of a remote repository, if that can be determined."
 1.11804 +msgstr ""
 1.11805 +
 1.11806 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11807 +#: ../en/ch10-hook.xml:1412
 1.11808 +msgid ""
 1.11809 +"If a hook exits with a status of zero, it is considered to have succeeded.  "
 1.11810 +"If it exits with a non-zero status, it is considered to have failed."
 1.11811 +msgstr ""
 1.11812 +
 1.11813 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11814 +#: ../en/ch10-hook.xml:1419
 1.11815 +msgid "Finding out where changesets come from"
 1.11816 +msgstr ""
 1.11817 +
 1.11818 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11819 +#: ../en/ch10-hook.xml:1421
 1.11820 +msgid ""
 1.11821 +"A hook that involves the transfer of changesets between a local repository "
 1.11822 +"and another may be able to find out information about the <quote>far side</"
 1.11823 +"quote>.  Mercurial knows <emphasis>how</emphasis> changes are being "
 1.11824 +"transferred, and in many cases <emphasis>where</emphasis> they are being "
 1.11825 +"transferred to or from."
 1.11826 +msgstr ""
 1.11827 +
 1.11828 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11829 +#: ../en/ch10-hook.xml:1430
 1.11830 +msgid "Sources of changesets"
 1.11831 +msgstr ""
 1.11832 +
 1.11833 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11834 +#: ../en/ch10-hook.xml:1432
 1.11835 +msgid ""
 1.11836 +"Mercurial will tell a hook what means are, or were, used to transfer "
 1.11837 +"changesets between repositories.  This is provided by Mercurial in a Python "
 1.11838 +"parameter named <literal>source</literal>, or an environment variable named "
 1.11839 +"<envar>HG_SOURCE</envar>."
 1.11840 +msgstr ""
 1.11841 +
 1.11842 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11843 +#: ../en/ch10-hook.xml:1440
 1.11844 +msgid ""
 1.11845 +"<literal>serve</literal>: Changesets are transferred to or from a remote "
 1.11846 +"repository over http or ssh."
 1.11847 +msgstr ""
 1.11848 +
 1.11849 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11850 +#: ../en/ch10-hook.xml:1445
 1.11851 +msgid ""
 1.11852 +"<literal>pull</literal>: Changesets are being transferred via a pull from one "
 1.11853 +"repository into another."
 1.11854 +msgstr ""
 1.11855 +
 1.11856 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11857 +#: ../en/ch10-hook.xml:1450
 1.11858 +msgid ""
 1.11859 +"<literal>push</literal>: Changesets are being transferred via a push from one "
 1.11860 +"repository into another."
 1.11861 +msgstr ""
 1.11862 +
 1.11863 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11864 +#: ../en/ch10-hook.xml:1455
 1.11865 +msgid ""
 1.11866 +"<literal>bundle</literal>: Changesets are being transferred to or from a "
 1.11867 +"bundle."
 1.11868 +msgstr ""
 1.11869 +
 1.11870 +#. type: Content of: <book><chapter><sect1><sect2><sect3><title>
 1.11871 +#: ../en/ch10-hook.xml:1462
 1.11872 +msgid "Where changes are going&emdash;remote repository URLs"
 1.11873 +msgstr ""
 1.11874 +
 1.11875 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11876 +#: ../en/ch10-hook.xml:1465
 1.11877 +msgid ""
 1.11878 +"When possible, Mercurial will tell a hook the location of the <quote>far "
 1.11879 +"side</quote> of an activity that transfers changeset data between "
 1.11880 +"repositories.  This is provided by Mercurial in a Python parameter named "
 1.11881 +"<literal>url</literal>, or an environment variable named <envar>HG_URL</"
 1.11882 +"envar>."
 1.11883 +msgstr ""
 1.11884 +
 1.11885 +#. type: Content of: <book><chapter><sect1><sect2><sect3><para>
 1.11886 +#: ../en/ch10-hook.xml:1473
 1.11887 +msgid ""
 1.11888 +"This information is not always known.  If a hook is invoked in a repository "
 1.11889 +"that is being served via http or ssh, Mercurial cannot tell where the remote "
 1.11890 +"repository is, but it may know where the client is connecting from.  In such "
 1.11891 +"cases, the URL will take one of the following forms:"
 1.11892 +msgstr ""
 1.11893 +
 1.11894 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11895 +#: ../en/ch10-hook.xml:1480
 1.11896 +msgid ""
 1.11897 +"<literal>remote:ssh:1.2.3.4</literal>&emdash;remote ssh client, at the IP "
 1.11898 +"address <literal>1.2.3.4</literal>."
 1.11899 +msgstr ""
 1.11900 +
 1.11901 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11902 +#: ../en/ch10-hook.xml:1485
 1.11903 +msgid ""
 1.11904 +"<literal>remote:http:1.2.3.4</literal>&emdash;remote http client, at the IP "
 1.11905 +"address <literal>1.2.3.4</literal>.  If the client is using SSL, this will be "
 1.11906 +"of the form <literal>remote:https:1.2.3.4</literal>."
 1.11907 +msgstr ""
 1.11908 +
 1.11909 +#. type: Content of: <book><chapter><sect1><sect2><sect3><itemizedlist><listitem><para>
 1.11910 +#: ../en/ch10-hook.xml:1492
 1.11911 +msgid "Empty&emdash;no information could be discovered about the remote client."
 1.11912 +msgstr ""
 1.11913 +
 1.11914 +#. type: Content of: <book><chapter><sect1><title>
 1.11915 +#: ../en/ch10-hook.xml:1501
 1.11916 +msgid "Hook reference"
 1.11917 +msgstr ""
 1.11918 +
 1.11919 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11920 +#: ../en/ch10-hook.xml:1504
 1.11921 +msgid ""
 1.11922 +"<literal role=\"hook\">changegroup</literal>&emdash;after remote changesets "
 1.11923 +"added"
 1.11924 +msgstr ""
 1.11925 +
 1.11926 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11927 +#: ../en/ch10-hook.xml:1507
 1.11928 +msgid ""
 1.11929 +"This hook is run after a group of pre-existing changesets has been added to "
 1.11930 +"the repository, for example via a <command role=\"hg-cmd\">hg pull</command> "
 1.11931 +"or <command role=\"hg-cmd\">hg unbundle</command>.  This hook is run once per "
 1.11932 +"operation that added one or more changesets.  This is in contrast to the "
 1.11933 +"<literal role=\"hook\">incoming</literal> hook, which is run once per "
 1.11934 +"changeset, regardless of whether the changesets arrive in a group."
 1.11935 +msgstr ""
 1.11936 +
 1.11937 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11938 +#: ../en/ch10-hook.xml:1517
 1.11939 +msgid ""
 1.11940 +"Some possible uses for this hook include kicking off an automated build or "
 1.11941 +"test of the added changesets, updating a bug database, or notifying "
 1.11942 +"subscribers that a repository contains new changes."
 1.11943 +msgstr ""
 1.11944 +
 1.11945 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11946 +#: ../en/ch10-hook.xml:1523 ../en/ch10-hook.xml:1564 ../en/ch10-hook.xml:1607
 1.11947 +#: ../en/ch10-hook.xml:1649 ../en/ch10-hook.xml:1704 ../en/ch10-hook.xml:1744
 1.11948 +#: ../en/ch10-hook.xml:1780 ../en/ch10-hook.xml:1815 ../en/ch10-hook.xml:1877
 1.11949 +#: ../en/ch10-hook.xml:1935 ../en/ch10-hook.xml:1969 ../en/ch10-hook.xml:1997
 1.11950 +msgid "Parameters to this hook:"
 1.11951 +msgstr ""
 1.11952 +
 1.11953 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11954 +#: ../en/ch10-hook.xml:1526 ../en/ch10-hook.xml:1880
 1.11955 +msgid ""
 1.11956 +"<literal>node</literal>: A changeset ID.  The changeset ID of the first "
 1.11957 +"changeset in the group that was added.  All changesets between this and "
 1.11958 +"\\index{tags!<literal>tip</literal>}<literal>tip</literal>, inclusive, were "
 1.11959 +"added by a single <command role=\"hg-cmd\">hg pull</command>, <command role="
 1.11960 +"\"hg-cmd\">hg push</command> or <command role=\"hg-cmd\">hg unbundle</"
 1.11961 +"command>."
 1.11962 +msgstr ""
 1.11963 +
 1.11964 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11965 +#: ../en/ch10-hook.xml:1536 ../en/ch10-hook.xml:1614 ../en/ch10-hook.xml:1707
 1.11966 +#: ../en/ch10-hook.xml:1890
 1.11967 +msgid ""
 1.11968 +"<literal>source</literal>: A string.  The source of these changes.  See "
 1.11969 +"section <xref linkend=\"sec.hook.sources\"/> for details."
 1.11970 +msgstr ""
 1.11971 +
 1.11972 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.11973 +#: ../en/ch10-hook.xml:1541 ../en/ch10-hook.xml:1619 ../en/ch10-hook.xml:1670
 1.11974 +#: ../en/ch10-hook.xml:1712 ../en/ch10-hook.xml:1794 ../en/ch10-hook.xml:1895
 1.11975 +msgid ""
 1.11976 +"<literal>url</literal>: A URL.  The location of the remote repository, if "
 1.11977 +"known.  See section <xref linkend=\"sec.hook.url\"/> for more information."
 1.11978 +msgstr ""
 1.11979 +
 1.11980 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11981 +#: ../en/ch10-hook.xml:1548
 1.11982 +msgid ""
 1.11983 +"See also: <literal role=\"hook\">incoming</literal> (section <xref linkend="
 1.11984 +"\"sec.hook.incoming\"/>), <literal role=\"hook\">prechangegroup</literal> "
 1.11985 +"(section <xref linkend=\"sec.hook.prechangegroup\"/>), <literal role=\"hook"
 1.11986 +"\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook."
 1.11987 +"pretxnchangegroup\"/>)"
 1.11988 +msgstr ""
 1.11989 +
 1.11990 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.11991 +#: ../en/ch10-hook.xml:1558
 1.11992 +msgid ""
 1.11993 +"<literal role=\"hook\">commit</literal>&emdash;after a new changeset is "
 1.11994 +"created"
 1.11995 +msgstr ""
 1.11996 +
 1.11997 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.11998 +#: ../en/ch10-hook.xml:1561
 1.11999 +msgid "This hook is run after a new changeset has been created."
 1.12000 +msgstr ""
 1.12001 +
 1.12002 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12003 +#: ../en/ch10-hook.xml:1567 ../en/ch10-hook.xml:1938
 1.12004 +msgid ""
 1.12005 +"<literal>node</literal>: A changeset ID.  The changeset ID of the newly "
 1.12006 +"committed changeset."
 1.12007 +msgstr ""
 1.12008 +
 1.12009 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12010 +#: ../en/ch10-hook.xml:1571 ../en/ch10-hook.xml:1942
 1.12011 +msgid ""
 1.12012 +"<literal>parent1</literal>: A changeset ID.  The changeset ID of the first "
 1.12013 +"parent of the newly committed changeset."
 1.12014 +msgstr ""
 1.12015 +
 1.12016 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12017 +#: ../en/ch10-hook.xml:1576 ../en/ch10-hook.xml:1947
 1.12018 +msgid ""
 1.12019 +"<literal>parent2</literal>: A changeset ID.  The changeset ID of the second "
 1.12020 +"parent of the newly committed changeset."
 1.12021 +msgstr ""
 1.12022 +
 1.12023 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12024 +#: ../en/ch10-hook.xml:1582
 1.12025 +msgid ""
 1.12026 +"See also: <literal role=\"hook\">precommit</literal> (section <xref linkend="
 1.12027 +"\"sec.hook.precommit\"/>), <literal role=\"hook\">pretxncommit</literal> "
 1.12028 +"(section <xref linkend=\"sec.hook.pretxncommit\"/>)"
 1.12029 +msgstr ""
 1.12030 +
 1.12031 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12032 +#: ../en/ch10-hook.xml:1590
 1.12033 +msgid ""
 1.12034 +"<literal role=\"hook\">incoming</literal>&emdash;after one remote changeset "
 1.12035 +"is added"
 1.12036 +msgstr ""
 1.12037 +
 1.12038 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12039 +#: ../en/ch10-hook.xml:1593
 1.12040 +msgid ""
 1.12041 +"This hook is run after a pre-existing changeset has been added to the "
 1.12042 +"repository, for example via a <command role=\"hg-cmd\">hg push</command>.  If "
 1.12043 +"a group of changesets was added in a single operation, this hook is called "
 1.12044 +"once for each added changeset."
 1.12045 +msgstr ""
 1.12046 +
 1.12047 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12048 +#: ../en/ch10-hook.xml:1600
 1.12049 +msgid ""
 1.12050 +"You can use this hook for the same purposes as the <literal role=\"hook"
 1.12051 +"\">changegroup</literal> hook (section <xref linkend=\"sec.hook.changegroup\"/"
 1.12052 +">); it's simply more convenient sometimes to run a hook once per group of "
 1.12053 +"changesets, while other times it's handier once per changeset."
 1.12054 +msgstr ""
 1.12055 +
 1.12056 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12057 +#: ../en/ch10-hook.xml:1610
 1.12058 +msgid ""
 1.12059 +"<literal>node</literal>: A changeset ID.  The ID of the newly added changeset."
 1.12060 +msgstr ""
 1.12061 +
 1.12062 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12063 +#: ../en/ch10-hook.xml:1626
 1.12064 +msgid ""
 1.12065 +"See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend="
 1.12066 +"\"sec.hook.changegroup\"/>) <literal role=\"hook\">prechangegroup</literal> "
 1.12067 +"(section <xref linkend=\"sec.hook.prechangegroup\"/>), <literal role=\"hook"
 1.12068 +"\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook."
 1.12069 +"pretxnchangegroup\"/>)"
 1.12070 +msgstr ""
 1.12071 +
 1.12072 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12073 +#: ../en/ch10-hook.xml:1636
 1.12074 +msgid ""
 1.12075 +"<literal role=\"hook\">outgoing</literal>&emdash;after changesets are "
 1.12076 +"propagated"
 1.12077 +msgstr ""
 1.12078 +
 1.12079 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12080 +#: ../en/ch10-hook.xml:1639
 1.12081 +msgid ""
 1.12082 +"This hook is run after a group of changesets has been propagated out of this "
 1.12083 +"repository, for example by a <command role=\"hg-cmd\">hg push</command> or "
 1.12084 +"<command role=\"hg-cmd\">hg bundle</command> command."
 1.12085 +msgstr ""
 1.12086 +
 1.12087 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12088 +#: ../en/ch10-hook.xml:1645
 1.12089 +msgid ""
 1.12090 +"One possible use for this hook is to notify administrators that changes have "
 1.12091 +"been pulled."
 1.12092 +msgstr ""
 1.12093 +
 1.12094 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12095 +#: ../en/ch10-hook.xml:1652
 1.12096 +msgid ""
 1.12097 +"<literal>node</literal>: A changeset ID.  The changeset ID of the first "
 1.12098 +"changeset of the group that was sent."
 1.12099 +msgstr ""
 1.12100 +
 1.12101 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12102 +#: ../en/ch10-hook.xml:1657
 1.12103 +msgid ""
 1.12104 +"<literal>source</literal>: A string.  The source of the of the operation (see "
 1.12105 +"section <xref linkend=\"sec.hook.sources\"/>).  If a remote client pulled "
 1.12106 +"changes from this repository, <literal>source</literal> will be "
 1.12107 +"<literal>serve</literal>.  If the client that obtained changes from this "
 1.12108 +"repository was local, <literal>source</literal> will be <literal>bundle</"
 1.12109 +"literal>, <literal>pull</literal>, or <literal>push</literal>, depending on "
 1.12110 +"the operation the client performed."
 1.12111 +msgstr ""
 1.12112 +
 1.12113 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12114 +#: ../en/ch10-hook.xml:1677
 1.12115 +msgid ""
 1.12116 +"See also: <literal role=\"hook\">preoutgoing</literal> (section <xref linkend="
 1.12117 +"\"sec.hook.preoutgoing\"/>)"
 1.12118 +msgstr ""
 1.12119 +
 1.12120 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12121 +#: ../en/ch10-hook.xml:1683
 1.12122 +msgid ""
 1.12123 +"<literal role=\"hook\">prechangegroup</literal>&emdash;before starting to add "
 1.12124 +"remote changesets"
 1.12125 +msgstr ""
 1.12126 +
 1.12127 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12128 +#: ../en/ch10-hook.xml:1687
 1.12129 +msgid ""
 1.12130 +"This controlling hook is run before Mercurial begins to add a group of "
 1.12131 +"changesets from another repository."
 1.12132 +msgstr ""
 1.12133 +
 1.12134 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12135 +#: ../en/ch10-hook.xml:1691
 1.12136 +msgid ""
 1.12137 +"This hook does not have any information about the changesets to be added, "
 1.12138 +"because it is run before transmission of those changesets is allowed to "
 1.12139 +"begin.  If this hook fails, the changesets will not be transmitted."
 1.12140 +msgstr ""
 1.12141 +
 1.12142 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12143 +#: ../en/ch10-hook.xml:1697
 1.12144 +msgid ""
 1.12145 +"One use for this hook is to prevent external changes from being added to a "
 1.12146 +"repository.  For example, you could use this to <quote>freeze</quote> a "
 1.12147 +"server-hosted branch temporarily or permanently so that users cannot push to "
 1.12148 +"it, while still allowing a local administrator to modify the repository."
 1.12149 +msgstr ""
 1.12150 +
 1.12151 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12152 +#: ../en/ch10-hook.xml:1719
 1.12153 +msgid ""
 1.12154 +"See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend="
 1.12155 +"\"sec.hook.changegroup\"/>), <literal role=\"hook\">incoming</literal> "
 1.12156 +"(section <xref linkend=\"sec.hook.incoming\"/>), , <literal role=\"hook"
 1.12157 +"\">pretxnchangegroup</literal> (section <xref linkend=\"sec.hook."
 1.12158 +"pretxnchangegroup\"/>)"
 1.12159 +msgstr ""
 1.12160 +
 1.12161 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12162 +#: ../en/ch10-hook.xml:1729
 1.12163 +msgid ""
 1.12164 +"<literal role=\"hook\">precommit</literal>&emdash;before starting to commit a "
 1.12165 +"changeset"
 1.12166 +msgstr ""
 1.12167 +
 1.12168 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12169 +#: ../en/ch10-hook.xml:1732
 1.12170 +msgid ""
 1.12171 +"This hook is run before Mercurial begins to commit a new changeset. It is run "
 1.12172 +"before Mercurial has any of the metadata for the commit, such as the files to "
 1.12173 +"be committed, the commit message, or the commit date."
 1.12174 +msgstr ""
 1.12175 +
 1.12176 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12177 +#: ../en/ch10-hook.xml:1738
 1.12178 +msgid ""
 1.12179 +"One use for this hook is to disable the ability to commit new changesets, "
 1.12180 +"while still allowing incoming changesets.  Another is to run a build or test, "
 1.12181 +"and only allow the commit to begin if the build or test succeeds."
 1.12182 +msgstr ""
 1.12183 +
 1.12184 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12185 +#: ../en/ch10-hook.xml:1747
 1.12186 +msgid ""
 1.12187 +"<literal>parent1</literal>: A changeset ID.  The changeset ID of the first "
 1.12188 +"parent of the working directory."
 1.12189 +msgstr ""
 1.12190 +
 1.12191 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12192 +#: ../en/ch10-hook.xml:1752
 1.12193 +msgid ""
 1.12194 +"<literal>parent2</literal>: A changeset ID.  The changeset ID of the second "
 1.12195 +"parent of the working directory."
 1.12196 +msgstr ""
 1.12197 +
 1.12198 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12199 +#: ../en/ch10-hook.xml:1757
 1.12200 +msgid ""
 1.12201 +"If the commit proceeds, the parents of the working directory will become the "
 1.12202 +"parents of the new changeset."
 1.12203 +msgstr ""
 1.12204 +
 1.12205 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12206 +#: ../en/ch10-hook.xml:1761
 1.12207 +msgid ""
 1.12208 +"See also: <literal role=\"hook\">commit</literal> (section <xref linkend="
 1.12209 +"\"sec.hook.commit\"/>), <literal role=\"hook\">pretxncommit</literal> "
 1.12210 +"(section <xref linkend=\"sec.hook.pretxncommit\"/>)"
 1.12211 +msgstr ""
 1.12212 +
 1.12213 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12214 +#: ../en/ch10-hook.xml:1769
 1.12215 +msgid ""
 1.12216 +"<literal role=\"hook\">preoutgoing</literal>&emdash;before starting to "
 1.12217 +"propagate changesets"
 1.12218 +msgstr ""
 1.12219 +
 1.12220 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12221 +#: ../en/ch10-hook.xml:1772
 1.12222 +msgid ""
 1.12223 +"This hook is invoked before Mercurial knows the identities of the changesets "
 1.12224 +"to be transmitted."
 1.12225 +msgstr ""
 1.12226 +
 1.12227 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12228 +#: ../en/ch10-hook.xml:1776
 1.12229 +msgid ""
 1.12230 +"One use for this hook is to prevent changes from being transmitted to another "
 1.12231 +"repository."
 1.12232 +msgstr ""
 1.12233 +
 1.12234 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12235 +#: ../en/ch10-hook.xml:1783
 1.12236 +msgid ""
 1.12237 +"<literal>source</literal>: A string.  The source of the operation that is "
 1.12238 +"attempting to obtain changes from this repository (see section <xref linkend="
 1.12239 +"\"sec.hook.sources\"/>).  See the documentation for the <literal>source</"
 1.12240 +"literal> parameter to the <literal role=\"hook\">outgoing</literal> hook, in "
 1.12241 +"section <xref linkend=\"sec.hook.outgoing\"/>, for possible values of this "
 1.12242 +"parameter."
 1.12243 +msgstr ""
 1.12244 +
 1.12245 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12246 +#: ../en/ch10-hook.xml:1801
 1.12247 +msgid ""
 1.12248 +"See also: <literal role=\"hook\">outgoing</literal> (section <xref linkend="
 1.12249 +"\"sec.hook.outgoing\"/>)"
 1.12250 +msgstr ""
 1.12251 +
 1.12252 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12253 +#: ../en/ch10-hook.xml:1807
 1.12254 +msgid ""
 1.12255 +"<literal role=\"hook\">pretag</literal>&emdash;before tagging a changeset"
 1.12256 +msgstr ""
 1.12257 +
 1.12258 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12259 +#: ../en/ch10-hook.xml:1810
 1.12260 +msgid ""
 1.12261 +"This controlling hook is run before a tag is created.  If the hook succeeds, "
 1.12262 +"creation of the tag proceeds.  If the hook fails, the tag is not created."
 1.12263 +msgstr ""
 1.12264 +
 1.12265 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12266 +#: ../en/ch10-hook.xml:1818
 1.12267 +msgid ""
 1.12268 +"<literal>local</literal>: A boolean.  Whether the tag is local to this "
 1.12269 +"repository instance (i.e. stored in <filename role=\"special\">.hg/localtags</"
 1.12270 +"filename>) or managed by Mercurial (stored in <filename role=\"special\">."
 1.12271 +"hgtags</filename>)."
 1.12272 +msgstr ""
 1.12273 +
 1.12274 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12275 +#: ../en/ch10-hook.xml:1825
 1.12276 +msgid ""
 1.12277 +"<literal>node</literal>: A changeset ID.  The ID of the changeset to be "
 1.12278 +"tagged."
 1.12279 +msgstr ""
 1.12280 +
 1.12281 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12282 +#: ../en/ch10-hook.xml:1829
 1.12283 +msgid "<literal>tag</literal>: A string.  The name of the tag to be created."
 1.12284 +msgstr ""
 1.12285 +
 1.12286 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12287 +#: ../en/ch10-hook.xml:1834
 1.12288 +msgid ""
 1.12289 +"If the tag to be created is revision-controlled, the <literal role=\"hook"
 1.12290 +"\">precommit</literal> and <literal role=\"hook\">pretxncommit</literal> "
 1.12291 +"hooks (sections <xref linkend=\"sec.hook.commit\"/> and <xref linkend=\"sec."
 1.12292 +"hook.pretxncommit\"/>) will also be run."
 1.12293 +msgstr ""
 1.12294 +
 1.12295 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12296 +#: ../en/ch10-hook.xml:1841
 1.12297 +msgid ""
 1.12298 +"See also: <literal role=\"hook\">tag</literal> (section <xref linkend=\"sec."
 1.12299 +"hook.tag\"/>)"
 1.12300 +msgstr ""
 1.12301 +
 1.12302 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12303 +#: ../en/ch10-hook.xml:1846
 1.12304 +msgid ""
 1.12305 +"<literal role=\"hook\">pretxnchangegroup</literal>&emdash;before completing "
 1.12306 +"addition of remote changesets"
 1.12307 +msgstr ""
 1.12308 +
 1.12309 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12310 +#: ../en/ch10-hook.xml:1850
 1.12311 +msgid ""
 1.12312 +"This controlling hook is run before a transaction&emdash;that manages the "
 1.12313 +"addition of a group of new changesets from outside the repository&emdash;"
 1.12314 +"completes.  If the hook succeeds, the transaction completes, and all of the "
 1.12315 +"changesets become permanent within this repository.  If the hook fails, the "
 1.12316 +"transaction is rolled back, and the data for the changesets is erased."
 1.12317 +msgstr ""
 1.12318 +
 1.12319 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12320 +#: ../en/ch10-hook.xml:1859
 1.12321 +msgid ""
 1.12322 +"This hook can access the metadata associated with the almost-added "
 1.12323 +"changesets, but it should not do anything permanent with this data. It must "
 1.12324 +"also not modify the working directory."
 1.12325 +msgstr ""
 1.12326 +
 1.12327 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12328 +#: ../en/ch10-hook.xml:1865
 1.12329 +msgid ""
 1.12330 +"While this hook is running, if other Mercurial processes access this "
 1.12331 +"repository, they will be able to see the almost-added changesets as if they "
 1.12332 +"are permanent.  This may lead to race conditions if you do not take steps to "
 1.12333 +"avoid them."
 1.12334 +msgstr ""
 1.12335 +
 1.12336 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12337 +#: ../en/ch10-hook.xml:1872
 1.12338 +msgid ""
 1.12339 +"This hook can be used to automatically vet a group of changesets.  If the "
 1.12340 +"hook fails, all of the changesets are <quote>rejected</quote> when the "
 1.12341 +"transaction rolls back."
 1.12342 +msgstr ""
 1.12343 +
 1.12344 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12345 +#: ../en/ch10-hook.xml:1902
 1.12346 +msgid ""
 1.12347 +"See also: <literal role=\"hook\">changegroup</literal> (section <xref linkend="
 1.12348 +"\"sec.hook.changegroup\"/>), <literal role=\"hook\">incoming</literal> "
 1.12349 +"(section <xref linkend=\"sec.hook.incoming\"/>), <literal role=\"hook"
 1.12350 +"\">prechangegroup</literal> (section <xref linkend=\"sec.hook.prechangegroup"
 1.12351 +"\"/>)"
 1.12352 +msgstr ""
 1.12353 +
 1.12354 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12355 +#: ../en/ch10-hook.xml:1912
 1.12356 +msgid ""
 1.12357 +"<literal role=\"hook\">pretxncommit</literal>&emdash;before completing commit "
 1.12358 +"of new changeset"
 1.12359 +msgstr ""
 1.12360 +
 1.12361 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12362 +#: ../en/ch10-hook.xml:1915
 1.12363 +msgid ""
 1.12364 +"This controlling hook is run before a transaction&emdash;that manages a new "
 1.12365 +"commit&emdash;completes.  If the hook succeeds, the transaction completes and "
 1.12366 +"the changeset becomes permanent within this repository.  If the hook fails, "
 1.12367 +"the transaction is rolled back, and the commit data is erased."
 1.12368 +msgstr ""
 1.12369 +
 1.12370 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12371 +#: ../en/ch10-hook.xml:1923
 1.12372 +msgid ""
 1.12373 +"This hook can access the metadata associated with the almost-new changeset, "
 1.12374 +"but it should not do anything permanent with this data.  It must also not "
 1.12375 +"modify the working directory."
 1.12376 +msgstr ""
 1.12377 +
 1.12378 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12379 +#: ../en/ch10-hook.xml:1929
 1.12380 +msgid ""
 1.12381 +"While this hook is running, if other Mercurial processes access this "
 1.12382 +"repository, they will be able to see the almost-new changeset as if it is "
 1.12383 +"permanent.  This may lead to race conditions if you do not take steps to "
 1.12384 +"avoid them."
 1.12385 +msgstr ""
 1.12386 +
 1.12387 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12388 +#: ../en/ch10-hook.xml:1953
 1.12389 +msgid ""
 1.12390 +"See also: <literal role=\"hook\">precommit</literal> (section <xref linkend="
 1.12391 +"\"sec.hook.precommit\"/>)"
 1.12392 +msgstr ""
 1.12393 +
 1.12394 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12395 +#: ../en/ch10-hook.xml:1959
 1.12396 +msgid ""
 1.12397 +"<literal role=\"hook\">preupdate</literal>&emdash;before updating or merging "
 1.12398 +"working directory"
 1.12399 +msgstr ""
 1.12400 +
 1.12401 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12402 +#: ../en/ch10-hook.xml:1962
 1.12403 +msgid ""
 1.12404 +"This controlling hook is run before an update or merge of the working "
 1.12405 +"directory begins.  It is run only if Mercurial's normal pre-update checks "
 1.12406 +"determine that the update or merge can proceed.  If the hook succeeds, the "
 1.12407 +"update or merge may proceed; if it fails, the update or merge does not start."
 1.12408 +msgstr ""
 1.12409 +
 1.12410 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12411 +#: ../en/ch10-hook.xml:1972
 1.12412 +msgid ""
 1.12413 +"<literal>parent1</literal>: A changeset ID.  The ID of the parent that the "
 1.12414 +"working directory is to be updated to.  If the working directory is being "
 1.12415 +"merged, it will not change this parent."
 1.12416 +msgstr ""
 1.12417 +
 1.12418 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12419 +#: ../en/ch10-hook.xml:1978
 1.12420 +msgid ""
 1.12421 +"<literal>parent2</literal>: A changeset ID.  Only set if the working "
 1.12422 +"directory is being merged.  The ID of the revision that the working directory "
 1.12423 +"is being merged with."
 1.12424 +msgstr ""
 1.12425 +
 1.12426 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12427 +#: ../en/ch10-hook.xml:1985
 1.12428 +msgid ""
 1.12429 +"See also: <literal role=\"hook\">update</literal> (section <xref linkend="
 1.12430 +"\"sec.hook.update\"/>)"
 1.12431 +msgstr ""
 1.12432 +
 1.12433 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12434 +#: ../en/ch10-hook.xml:1991
 1.12435 +msgid "<literal role=\"hook\">tag</literal>&emdash;after tagging a changeset"
 1.12436 +msgstr ""
 1.12437 +
 1.12438 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12439 +#: ../en/ch10-hook.xml:1994
 1.12440 +msgid "This hook is run after a tag has been created."
 1.12441 +msgstr ""
 1.12442 +
 1.12443 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12444 +#: ../en/ch10-hook.xml:2000
 1.12445 +msgid ""
 1.12446 +"<literal>local</literal>: A boolean.  Whether the new tag is local to this "
 1.12447 +"repository instance (i.e.  stored in <filename role=\"special\">.hg/"
 1.12448 +"localtags</filename>) or managed by Mercurial (stored in <filename role="
 1.12449 +"\"special\">.hgtags</filename>)."
 1.12450 +msgstr ""
 1.12451 +
 1.12452 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12453 +#: ../en/ch10-hook.xml:2008
 1.12454 +msgid ""
 1.12455 +"<literal>node</literal>: A changeset ID.  The ID of the changeset that was "
 1.12456 +"tagged."
 1.12457 +msgstr ""
 1.12458 +
 1.12459 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12460 +#: ../en/ch10-hook.xml:2012
 1.12461 +msgid "<literal>tag</literal>: A string.  The name of the tag that was created."
 1.12462 +msgstr ""
 1.12463 +
 1.12464 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12465 +#: ../en/ch10-hook.xml:2017
 1.12466 +msgid ""
 1.12467 +"If the created tag is revision-controlled, the <literal role=\"hook\">commit</"
 1.12468 +"literal> hook (section <xref linkend=\"sec.hook.commit\"/>) is run before "
 1.12469 +"this hook."
 1.12470 +msgstr ""
 1.12471 +
 1.12472 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12473 +#: ../en/ch10-hook.xml:2022
 1.12474 +msgid ""
 1.12475 +"See also: <literal role=\"hook\">pretag</literal> (section <xref linkend="
 1.12476 +"\"sec.hook.pretag\"/>)"
 1.12477 +msgstr ""
 1.12478 +
 1.12479 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12480 +#: ../en/ch10-hook.xml:2028
 1.12481 +msgid ""
 1.12482 +"<literal role=\"hook\">update</literal>&emdash;after updating or merging "
 1.12483 +"working directory"
 1.12484 +msgstr ""
 1.12485 +
 1.12486 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12487 +#: ../en/ch10-hook.xml:2031
 1.12488 +msgid ""
 1.12489 +"This hook is run after an update or merge of the working directory "
 1.12490 +"completes.  Since a merge can fail (if the external <command>hgmerge</"
 1.12491 +"command> command fails to resolve conflicts in a file), this hook "
 1.12492 +"communicates whether the update or merge completed cleanly."
 1.12493 +msgstr ""
 1.12494 +
 1.12495 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12496 +#: ../en/ch10-hook.xml:2039
 1.12497 +msgid ""
 1.12498 +"<literal>error</literal>: A boolean.  Indicates whether the update or merge "
 1.12499 +"completed successfully."
 1.12500 +msgstr ""
 1.12501 +
 1.12502 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12503 +#: ../en/ch10-hook.xml:2044
 1.12504 +msgid ""
 1.12505 +"<literal>parent1</literal>: A changeset ID.  The ID of the parent that the "
 1.12506 +"working directory was updated to.  If the working directory was merged, it "
 1.12507 +"will not have changed this parent."
 1.12508 +msgstr ""
 1.12509 +
 1.12510 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.12511 +#: ../en/ch10-hook.xml:2050
 1.12512 +msgid ""
 1.12513 +"<literal>parent2</literal>: A changeset ID.  Only set if the working "
 1.12514 +"directory was merged.  The ID of the revision that the working directory was "
 1.12515 +"merged with."
 1.12516 +msgstr ""
 1.12517 +
 1.12518 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12519 +#: ../en/ch10-hook.xml:2056
 1.12520 +msgid ""
 1.12521 +"See also: <literal role=\"hook\">preupdate</literal> (section <xref linkend="
 1.12522 +"\"sec.hook.preupdate\"/>)"
 1.12523 +msgstr ""
 1.12524 +
 1.12525 +#. type: Content of: <book><chapter><title>
 1.12526 +#: ../en/ch11-template.xml:5
 1.12527 +msgid "Customising the output of Mercurial"
 1.12528 +msgstr "定制 Mercurial 的输出"
 1.12529 +
 1.12530 +#. type: Content of: <book><chapter><para>
 1.12531 +#: ../en/ch11-template.xml:7
 1.12532 +msgid ""
 1.12533 +"Mercurial provides a powerful mechanism to let you control how it displays "
 1.12534 +"information.  The mechanism is based on templates.  You can use templates to "
 1.12535 +"generate specific output for a single command, or to customise the entire "
 1.12536 +"appearance of the built-in web interface."
 1.12537 +msgstr ""
 1.12538 +
 1.12539 +#. type: Content of: <book><chapter><sect1><title>
 1.12540 +#: ../en/ch11-template.xml:14
 1.12541 +msgid "Using precanned output styles"
 1.12542 +msgstr ""
 1.12543 +
 1.12544 +#. type: Content of: <book><chapter><sect1><para>
 1.12545 +#: ../en/ch11-template.xml:16
 1.12546 +msgid ""
 1.12547 +"Packaged with Mercurial are some output styles that you can use immediately.  "
 1.12548 +"A style is simply a precanned template that someone wrote and installed "
 1.12549 +"somewhere that Mercurial can find."
 1.12550 +msgstr ""
 1.12551 +
 1.12552 +#. type: Content of: <book><chapter><sect1><para>
 1.12553 +#: ../en/ch11-template.xml:21
 1.12554 +msgid ""
 1.12555 +"Before we take a look at Mercurial's bundled styles, let's review its normal "
 1.12556 +"output."
 1.12557 +msgstr ""
 1.12558 +
 1.12559 +#. type: Content of: <book><chapter><sect1><para>
 1.12560 +#: ../en/ch11-template.xml:26
 1.12561 +msgid ""
 1.12562 +"This is somewhat informative, but it takes up a lot of space&emdash;five "
 1.12563 +"lines of output per changeset.  The <literal>compact</literal> style reduces "
 1.12564 +"this to three lines, presented in a sparse manner."
 1.12565 +msgstr ""
 1.12566 +
 1.12567 +#. type: Content of: <book><chapter><sect1><para>
 1.12568 +#: ../en/ch11-template.xml:33
 1.12569 +msgid ""
 1.12570 +"The <literal>changelog</literal> style hints at the expressive power of "
 1.12571 +"Mercurial's templating engine.  This style attempts to follow the GNU "
 1.12572 +"Project's changelog guidelines<citation>web:changelog</citation>."
 1.12573 +msgstr ""
 1.12574 +
 1.12575 +#. type: Content of: <book><chapter><sect1><para>
 1.12576 +#: ../en/ch11-template.xml:40
 1.12577 +msgid ""
 1.12578 +"You will not be shocked to learn that Mercurial's default output style is "
 1.12579 +"named <literal>default</literal>."
 1.12580 +msgstr ""
 1.12581 +
 1.12582 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.12583 +#: ../en/ch11-template.xml:44
 1.12584 +msgid "Setting a default style"
 1.12585 +msgstr ""
 1.12586 +
 1.12587 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12588 +#: ../en/ch11-template.xml:46
 1.12589 +msgid ""
 1.12590 +"You can modify the output style that Mercurial will use for every command by "
 1.12591 +"editing your <filename role=\"special\"> /.hgrc</filename>\\ file, naming the "
 1.12592 +"style you would prefer to use."
 1.12593 +msgstr ""
 1.12594 +
 1.12595 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.12596 +#: ../en/ch11-template.xml:53
 1.12597 +msgid ""
 1.12598 +"If you write a style of your own, you can use it by either providing the path "
 1.12599 +"to your style file, or copying your style file into a location where "
 1.12600 +"Mercurial can find it (typically the <literal>templates</literal> "
 1.12601 +"subdirectory of your Mercurial install directory)."
 1.12602 +msgstr ""
 1.12603 +
 1.12604 +#. type: Content of: <book><chapter><sect1><title>
 1.12605 +#: ../en/ch11-template.xml:62
 1.12606 +msgid "Commands that support styles and templates"
 1.12607 +msgstr ""
 1.12608 +
 1.12609 +#. type: Content of: <book><chapter><sect1><para>
 1.12610 +#: ../en/ch11-template.xml:64
 1.12611 +msgid ""
 1.12612 +"All of Mercurial's <quote><literal>log</literal>-like</quote> commands let "
 1.12613 +"you use styles and templates: <command role=\"hg-cmd\">hg incoming</command>, "
 1.12614 +"<command role=\"hg-cmd\">hg log</command>, <command role=\"hg-cmd\">hg "
 1.12615 +"outgoing</command>, and <command role=\"hg-cmd\">hg tip</command>."
 1.12616 +msgstr ""
 1.12617 +
 1.12618 +#. type: Content of: <book><chapter><sect1><para>
 1.12619 +#: ../en/ch11-template.xml:71
 1.12620 +msgid ""
 1.12621 +"As I write this manual, these are so far the only commands that support "
 1.12622 +"styles and templates.  Since these are the most important commands that need "
 1.12623 +"customisable output, there has been little pressure from the Mercurial user "
 1.12624 +"community to add style and template support to other commands."
 1.12625 +msgstr ""
 1.12626 +
 1.12627 +#. type: Content of: <book><chapter><sect1><title>
 1.12628 +#: ../en/ch11-template.xml:79
 1.12629 +msgid "The basics of templating"
 1.12630 +msgstr ""
 1.12631 +
 1.12632 +#. type: Content of: <book><chapter><sect1><para>
 1.12633 +#: ../en/ch11-template.xml:81
 1.12634 +msgid ""
 1.12635 +"At its simplest, a Mercurial template is a piece of text.  Some of the text "
 1.12636 +"never changes, while other parts are <emphasis>expanded</emphasis>, or "
 1.12637 +"replaced with new text, when necessary."
 1.12638 +msgstr ""
 1.12639 +
 1.12640 +#. type: Content of: <book><chapter><sect1><para>
 1.12641 +#: ../en/ch11-template.xml:86
 1.12642 +msgid ""
 1.12643 +"Before we continue, let's look again at a simple example of Mercurial's "
 1.12644 +"normal output."
 1.12645 +msgstr ""
 1.12646 +
 1.12647 +#. type: Content of: <book><chapter><sect1><para>
 1.12648 +#: ../en/ch11-template.xml:91
 1.12649 +msgid ""
 1.12650 +"Now, let's run the same command, but using a template to change its output."
 1.12651 +msgstr ""
 1.12652 +
 1.12653 +#. type: Content of: <book><chapter><sect1><para>
 1.12654 +#: ../en/ch11-template.xml:96
 1.12655 +msgid ""
 1.12656 +"The example above illustrates the simplest possible template; it's just a "
 1.12657 +"piece of static text, printed once for each changeset.  The <option role=\"hg-"
 1.12658 +"opt-log\">--template</option> option to the <command role=\"hg-cmd\">hg log</"
 1.12659 +"command> command tells Mercurial to use the given text as the template when "
 1.12660 +"printing each changeset."
 1.12661 +msgstr ""
 1.12662 +
 1.12663 +#. type: Content of: <book><chapter><sect1><para>
 1.12664 +#: ../en/ch11-template.xml:104
 1.12665 +msgid ""
 1.12666 +"Notice that the template string above ends with the text <quote><literal>\\n</"
 1.12667 +"literal></quote>.  This is an <emphasis>escape sequence</emphasis>, telling "
 1.12668 +"Mercurial to print a newline at the end of each template item.  If you omit "
 1.12669 +"this newline, Mercurial will run each piece of output together.  See section "
 1.12670 +"<xref linkend=\"sec.template.escape\"/> for more details of escape sequences."
 1.12671 +msgstr ""
 1.12672 +
 1.12673 +#. type: Content of: <book><chapter><sect1><para>
 1.12674 +#: ../en/ch11-template.xml:112
 1.12675 +msgid ""
 1.12676 +"A template that prints a fixed string of text all the time isn't very useful; "
 1.12677 +"let's try something a bit more complex."
 1.12678 +msgstr ""
 1.12679 +
 1.12680 +#. type: Content of: <book><chapter><sect1><para>
 1.12681 +#: ../en/ch11-template.xml:118
 1.12682 +msgid ""
 1.12683 +"As you can see, the string <quote><literal>{desc}</literal></quote> in the "
 1.12684 +"template has been replaced in the output with the description of each "
 1.12685 +"changeset.  Every time Mercurial finds text enclosed in curly braces "
 1.12686 +"(<quote><literal>{</literal></quote> and <quote><literal>}</literal></"
 1.12687 +"quote>), it will try to replace the braces and text with the expansion of "
 1.12688 +"whatever is inside.  To print a literal curly brace, you must escape it, as "
 1.12689 +"described in section <xref linkend=\"sec.template.escape\"/>."
 1.12690 +msgstr ""
 1.12691 +
 1.12692 +#. type: Content of: <book><chapter><sect1><title>
 1.12693 +#: ../en/ch11-template.xml:131
 1.12694 +msgid "Common template keywords"
 1.12695 +msgstr ""
 1.12696 +
 1.12697 +#. type: Content of: <book><chapter><sect1><para>
 1.12698 +#: ../en/ch11-template.xml:133
 1.12699 +msgid ""
 1.12700 +"You can start writing simple templates immediately using the keywords below."
 1.12701 +msgstr ""
 1.12702 +
 1.12703 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12704 +#: ../en/ch11-template.xml:137
 1.12705 +msgid ""
 1.12706 +"<literal role=\"template-keyword\">author</literal>: String.  The unmodified "
 1.12707 +"author of the changeset."
 1.12708 +msgstr ""
 1.12709 +
 1.12710 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12711 +#: ../en/ch11-template.xml:141
 1.12712 +msgid ""
 1.12713 +"<literal role=\"template-keyword\">branches</literal>: String.  The name of "
 1.12714 +"the branch on which the changeset was committed.  Will be empty if the branch "
 1.12715 +"name was <literal>default</literal>."
 1.12716 +msgstr ""
 1.12717 +
 1.12718 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12719 +#: ../en/ch11-template.xml:147
 1.12720 +msgid ""
 1.12721 +"<literal role=\"template-keyword\">date</literal>: Date information.  The "
 1.12722 +"date when the changeset was committed.  This is <emphasis>not</emphasis> "
 1.12723 +"human-readable; you must pass it through a filter that will render it "
 1.12724 +"appropriately.  See section <xref linkend=\"sec.template.filter\"/> for more "
 1.12725 +"information on filters. The date is expressed as a pair of numbers.  The "
 1.12726 +"first number is a Unix UTC timestamp (seconds since January 1, 1970); the "
 1.12727 +"second is the offset of the committer's timezone from UTC, in seconds."
 1.12728 +msgstr ""
 1.12729 +
 1.12730 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12731 +#: ../en/ch11-template.xml:158
 1.12732 +msgid ""
 1.12733 +"<literal role=\"template-keyword\">desc</literal>: String.  The text of the "
 1.12734 +"changeset description."
 1.12735 +msgstr ""
 1.12736 +
 1.12737 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12738 +#: ../en/ch11-template.xml:161
 1.12739 +msgid ""
 1.12740 +"<literal role=\"template-keyword\">files</literal>: List of strings.  All "
 1.12741 +"files modified, added, or removed by this changeset."
 1.12742 +msgstr ""
 1.12743 +
 1.12744 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12745 +#: ../en/ch11-template.xml:166
 1.12746 +msgid ""
 1.12747 +"<literal role=\"template-keyword\">file_adds</literal>: List of strings.  "
 1.12748 +"Files added by this changeset."
 1.12749 +msgstr ""
 1.12750 +
 1.12751 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12752 +#: ../en/ch11-template.xml:170
 1.12753 +msgid ""
 1.12754 +"<literal role=\"template-keyword\">file_dels</literal>: List of strings.  "
 1.12755 +"Files removed by this changeset."
 1.12756 +msgstr ""
 1.12757 +
 1.12758 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12759 +#: ../en/ch11-template.xml:174
 1.12760 +msgid ""
 1.12761 +"<literal role=\"template-keyword\">node</literal>: String.  The changeset "
 1.12762 +"identification hash, as a 40-character hexadecimal string."
 1.12763 +msgstr ""
 1.12764 +
 1.12765 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12766 +#: ../en/ch11-template.xml:178
 1.12767 +msgid ""
 1.12768 +"<literal role=\"template-keyword\">parents</literal>: List of strings.  The "
 1.12769 +"parents of the changeset."
 1.12770 +msgstr ""
 1.12771 +
 1.12772 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12773 +#: ../en/ch11-template.xml:182
 1.12774 +msgid ""
 1.12775 +"<literal role=\"template-keyword\">rev</literal>: Integer.  The repository-"
 1.12776 +"local changeset revision number."
 1.12777 +msgstr ""
 1.12778 +
 1.12779 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12780 +#: ../en/ch11-template.xml:186
 1.12781 +msgid ""
 1.12782 +"<literal role=\"template-keyword\">tags</literal>: List of strings.  Any tags "
 1.12783 +"associated with the changeset."
 1.12784 +msgstr ""
 1.12785 +
 1.12786 +#. type: Content of: <book><chapter><sect1><para>
 1.12787 +#: ../en/ch11-template.xml:191
 1.12788 +msgid ""
 1.12789 +"A few simple experiments will show us what to expect when we use these "
 1.12790 +"keywords; you can see the results below."
 1.12791 +msgstr ""
 1.12792 +
 1.12793 +#. type: Content of: <book><chapter><sect1><para>
 1.12794 +#: ../en/ch11-template.xml:196
 1.12795 +msgid ""
 1.12796 +"As we noted above, the date keyword does not produce human-readable output, "
 1.12797 +"so we must treat it specially.  This involves using a <emphasis>filter</"
 1.12798 +"emphasis>, about which more in section <xref linkend=\"sec.template.filter\"/"
 1.12799 +">."
 1.12800 +msgstr ""
 1.12801 +
 1.12802 +#. type: Content of: <book><chapter><sect1><title>
 1.12803 +#: ../en/ch11-template.xml:206
 1.12804 +msgid "Escape sequences"
 1.12805 +msgstr ""
 1.12806 +
 1.12807 +#. type: Content of: <book><chapter><sect1><para>
 1.12808 +#: ../en/ch11-template.xml:208
 1.12809 +msgid ""
 1.12810 +"Mercurial's templating engine recognises the most commonly used escape "
 1.12811 +"sequences in strings.  When it sees a backslash (<quote><literal>\\</"
 1.12812 +"literal></quote>) character, it looks at the following character and "
 1.12813 +"substitutes the two characters with a single replacement, as described below."
 1.12814 +msgstr ""
 1.12815 +
 1.12816 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12817 +#: ../en/ch11-template.xml:215
 1.12818 +msgid ""
 1.12819 +"<literal>\\textbackslash\\textbackslash</literal>: Backslash, <quote><literal>"
 1.12820 +"\\</literal></quote>, ASCII 134."
 1.12821 +msgstr ""
 1.12822 +
 1.12823 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12824 +#: ../en/ch11-template.xml:219
 1.12825 +msgid "<literal>\\textbackslash n</literal>: Newline, ASCII 12."
 1.12826 +msgstr ""
 1.12827 +
 1.12828 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12829 +#: ../en/ch11-template.xml:222
 1.12830 +msgid "<literal>\\textbackslash r</literal>: Carriage return, ASCII 15."
 1.12831 +msgstr ""
 1.12832 +
 1.12833 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12834 +#: ../en/ch11-template.xml:225
 1.12835 +msgid "<literal>\\textbackslash t</literal>: Tab, ASCII 11."
 1.12836 +msgstr ""
 1.12837 +
 1.12838 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12839 +#: ../en/ch11-template.xml:228
 1.12840 +msgid "<literal>\\textbackslash v</literal>: Vertical tab, ASCII 13."
 1.12841 +msgstr ""
 1.12842 +
 1.12843 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12844 +#: ../en/ch11-template.xml:231
 1.12845 +msgid ""
 1.12846 +"<literal>\\textbackslash {</literal>: Open curly brace, <quote><literal>{</"
 1.12847 +"literal></quote>, ASCII 173."
 1.12848 +msgstr ""
 1.12849 +
 1.12850 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12851 +#: ../en/ch11-template.xml:235
 1.12852 +msgid ""
 1.12853 +"<literal>\\textbackslash }</literal>: Close curly brace, <quote><literal>}</"
 1.12854 +"literal></quote>, ASCII 175."
 1.12855 +msgstr ""
 1.12856 +
 1.12857 +#. type: Content of: <book><chapter><sect1><para>
 1.12858 +#: ../en/ch11-template.xml:240
 1.12859 +msgid ""
 1.12860 +"As indicated above, if you want the expansion of a template to contain a "
 1.12861 +"literal <quote><literal>\\</literal></quote>, <quote><literal>{</literal></"
 1.12862 +"quote>, or <quote><literal>{</literal></quote> character, you must escape it."
 1.12863 +msgstr ""
 1.12864 +
 1.12865 +#. type: Content of: <book><chapter><sect1><title>
 1.12866 +#: ../en/ch11-template.xml:248
 1.12867 +msgid "Filtering keywords to change their results"
 1.12868 +msgstr ""
 1.12869 +
 1.12870 +#. type: Content of: <book><chapter><sect1><para>
 1.12871 +#: ../en/ch11-template.xml:250
 1.12872 +msgid ""
 1.12873 +"Some of the results of template expansion are not immediately easy to use.  "
 1.12874 +"Mercurial lets you specify an optional chain of <emphasis>filters</emphasis> "
 1.12875 +"to modify the result of expanding a keyword.  You have already seen a common "
 1.12876 +"filter, <literal role=\"template-kw-filt-date\">isodate</literal>, in action "
 1.12877 +"above, to make a date readable."
 1.12878 +msgstr ""
 1.12879 +
 1.12880 +#. type: Content of: <book><chapter><sect1><para>
 1.12881 +#: ../en/ch11-template.xml:257
 1.12882 +msgid ""
 1.12883 +"Below is a list of the most commonly used filters that Mercurial supports.  "
 1.12884 +"While some filters can be applied to any text, others can only be used in "
 1.12885 +"specific circumstances.  The name of each filter is followed first by an "
 1.12886 +"indication of where it can be used, then a description of its effect."
 1.12887 +msgstr ""
 1.12888 +
 1.12889 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12890 +#: ../en/ch11-template.xml:264
 1.12891 +msgid ""
 1.12892 +"<literal role=\"template-filter\">addbreaks</literal>: Any text. Add an XHTML "
 1.12893 +"<quote><literal>&lt;br/&gt;</literal></quote> tag before the end of every "
 1.12894 +"line except the last.  For example, <quote><literal>foo\\nbar</literal></"
 1.12895 +"quote> becomes <quote><literal>foo&lt;br/&gt;\\nbar</literal></quote>."
 1.12896 +msgstr ""
 1.12897 +
 1.12898 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12899 +#: ../en/ch11-template.xml:271
 1.12900 +msgid ""
 1.12901 +"<literal role=\"template-kw-filt-date\">age</literal>: <literal role="
 1.12902 +"\"template-keyword\">date</literal> keyword.  Render the age of the date, "
 1.12903 +"relative to the current time.  Yields a string like <quote><literal>10 "
 1.12904 +"minutes</literal></quote>."
 1.12905 +msgstr ""
 1.12906 +
 1.12907 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12908 +#: ../en/ch11-template.xml:278
 1.12909 +msgid ""
 1.12910 +"<literal role=\"template-filter\">basename</literal>: Any text, but most "
 1.12911 +"useful for the <literal role=\"template-keyword\">files</literal> keyword and "
 1.12912 +"its relatives.  Treat the text as a path, and return the basename. For "
 1.12913 +"example, <quote><literal>foo/bar/baz</literal></quote> becomes "
 1.12914 +"<quote><literal>baz</literal></quote>."
 1.12915 +msgstr ""
 1.12916 +
 1.12917 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12918 +#: ../en/ch11-template.xml:287
 1.12919 +msgid ""
 1.12920 +"<literal role=\"template-kw-filt-date\">date</literal>: <literal role="
 1.12921 +"\"template-keyword\">date</literal> keyword.  Render a date in a similar "
 1.12922 +"format to the Unix <literal role=\"template-keyword\">date</literal> command, "
 1.12923 +"but with timezone included.  Yields a string like <quote><literal>Mon Sep 04 "
 1.12924 +"15:13:13 2006 -0700</literal></quote>."
 1.12925 +msgstr ""
 1.12926 +
 1.12927 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12928 +#: ../en/ch11-template.xml:295
 1.12929 +msgid ""
 1.12930 +"<literal role=\"template-kw-filt-author\">domain</literal>: Any text, but "
 1.12931 +"most useful for the <literal role=\"template-keyword\">author</literal> "
 1.12932 +"keyword.  Finds the first string that looks like an email address, and "
 1.12933 +"extract just the domain component.  For example, <quote><literal>Bryan "
 1.12934 +"O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> becomes "
 1.12935 +"<quote><literal>serpentine.com</literal></quote>."
 1.12936 +msgstr ""
 1.12937 +
 1.12938 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12939 +#: ../en/ch11-template.xml:305
 1.12940 +msgid ""
 1.12941 +"<literal role=\"template-kw-filt-author\">email</literal>: Any text, but most "
 1.12942 +"useful for the <literal role=\"template-keyword\">author</literal> keyword.  "
 1.12943 +"Extract the first string that looks like an email address.  For example, "
 1.12944 +"<quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> "
 1.12945 +"becomes <quote><literal>bos@serpentine.com</literal></quote>."
 1.12946 +msgstr ""
 1.12947 +
 1.12948 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12949 +#: ../en/ch11-template.xml:314
 1.12950 +msgid ""
 1.12951 +"<literal role=\"template-filter\">escape</literal>: Any text.  Replace the "
 1.12952 +"special XML/XHTML characters <quote><literal>&amp;</literal></quote>, "
 1.12953 +"<quote><literal>&lt;</literal></quote> and <quote><literal>&gt;</literal></"
 1.12954 +"quote> with XML entities."
 1.12955 +msgstr ""
 1.12956 +
 1.12957 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12958 +#: ../en/ch11-template.xml:322
 1.12959 +msgid ""
 1.12960 +"<literal role=\"template-filter\">fill68</literal>: Any text.  Wrap the text "
 1.12961 +"to fit in 68 columns.  This is useful before you pass text through the "
 1.12962 +"<literal role=\"template-filter\">tabindent</literal> filter, and still want "
 1.12963 +"it to fit in an 80-column fixed-font window."
 1.12964 +msgstr ""
 1.12965 +
 1.12966 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12967 +#: ../en/ch11-template.xml:330
 1.12968 +msgid ""
 1.12969 +"<literal role=\"template-filter\">fill76</literal>: Any text.  Wrap the text "
 1.12970 +"to fit in 76 columns."
 1.12971 +msgstr ""
 1.12972 +
 1.12973 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12974 +#: ../en/ch11-template.xml:334
 1.12975 +msgid ""
 1.12976 +"<literal role=\"template-filter\">firstline</literal>: Any text.  Yield the "
 1.12977 +"first line of text, without any trailing newlines."
 1.12978 +msgstr ""
 1.12979 +
 1.12980 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12981 +#: ../en/ch11-template.xml:339
 1.12982 +msgid ""
 1.12983 +"<literal role=\"template-kw-filt-date\">hgdate</literal>: <literal role="
 1.12984 +"\"template-keyword\">date</literal> keyword.  Render the date as a pair of "
 1.12985 +"readable numbers.  Yields a string like <quote><literal>1157407993 25200</"
 1.12986 +"literal></quote>."
 1.12987 +msgstr ""
 1.12988 +
 1.12989 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12990 +#: ../en/ch11-template.xml:346
 1.12991 +msgid ""
 1.12992 +"<literal role=\"template-kw-filt-date\">isodate</literal>: <literal role="
 1.12993 +"\"template-keyword\">date</literal> keyword.  Render the date as a text "
 1.12994 +"string in ISO 8601 format.  Yields a string like <quote><literal>2006-09-04 "
 1.12995 +"15:13:13 -0700</literal></quote>."
 1.12996 +msgstr ""
 1.12997 +
 1.12998 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.12999 +#: ../en/ch11-template.xml:353
 1.13000 +msgid ""
 1.13001 +"<literal role=\"template-filter\">obfuscate</literal>: Any text, but most "
 1.13002 +"useful for the <literal role=\"template-keyword\">author</literal> keyword.  "
 1.13003 +"Yield the input text rendered as a sequence of XML entities.  This helps to "
 1.13004 +"defeat some particularly stupid screen-scraping email harvesting spambots."
 1.13005 +msgstr ""
 1.13006 +
 1.13007 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13008 +#: ../en/ch11-template.xml:361
 1.13009 +msgid ""
 1.13010 +"<literal role=\"template-kw-filt-author\">person</literal>: Any text, but "
 1.13011 +"most useful for the <literal role=\"template-keyword\">author</literal> "
 1.13012 +"keyword.  Yield the text before an email address. For example, "
 1.13013 +"<quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> "
 1.13014 +"becomes <quote><literal>Bryan O'Sullivan</literal></quote>."
 1.13015 +msgstr ""
 1.13016 +
 1.13017 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13018 +#: ../en/ch11-template.xml:370
 1.13019 +msgid ""
 1.13020 +"<literal role=\"template-kw-filt-date\">rfc822date</literal>: <literal role="
 1.13021 +"\"template-keyword\">date</literal> keyword.  Render a date using the same "
 1.13022 +"format used in email headers.  Yields a string like <quote><literal>Mon, 04 "
 1.13023 +"Sep 2006 15:13:13 -0700</literal></quote>."
 1.13024 +msgstr ""
 1.13025 +
 1.13026 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13027 +#: ../en/ch11-template.xml:377
 1.13028 +msgid ""
 1.13029 +"<literal role=\"template-kw-filt-node\">short</literal>: Changeset hash.  "
 1.13030 +"Yield the short form of a changeset hash, i.e. a 12-character hexadecimal "
 1.13031 +"string."
 1.13032 +msgstr ""
 1.13033 +
 1.13034 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13035 +#: ../en/ch11-template.xml:382
 1.13036 +msgid ""
 1.13037 +"<literal role=\"template-kw-filt-date\">shortdate</literal>: <literal role="
 1.13038 +"\"template-keyword\">date</literal> keyword.  Render the year, month, and day "
 1.13039 +"of the date.  Yields a string like <quote><literal>2006-09-04</literal></"
 1.13040 +"quote>."
 1.13041 +msgstr ""
 1.13042 +
 1.13043 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13044 +#: ../en/ch11-template.xml:388
 1.13045 +msgid ""
 1.13046 +"<literal role=\"template-filter\">strip</literal>: Any text.  Strip all "
 1.13047 +"leading and trailing whitespace from the string."
 1.13048 +msgstr ""
 1.13049 +
 1.13050 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13051 +#: ../en/ch11-template.xml:392
 1.13052 +msgid ""
 1.13053 +"<literal role=\"template-filter\">tabindent</literal>: Any text.  Yield the "
 1.13054 +"text, with every line except the first starting with a tab character."
 1.13055 +msgstr ""
 1.13056 +
 1.13057 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13058 +#: ../en/ch11-template.xml:397
 1.13059 +msgid ""
 1.13060 +"<literal role=\"template-filter\">urlescape</literal>: Any text.  Escape all "
 1.13061 +"characters that are considered <quote>special</quote> by URL parsers.  For "
 1.13062 +"example, <literal>foo bar</literal> becomes <literal>foo%20bar</literal>."
 1.13063 +msgstr ""
 1.13064 +
 1.13065 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.13066 +#: ../en/ch11-template.xml:404
 1.13067 +msgid ""
 1.13068 +"<literal role=\"template-kw-filt-author\">user</literal>: Any text, but most "
 1.13069 +"useful for the <literal role=\"template-keyword\">author</literal> keyword.  "
 1.13070 +"Return the <quote>user</quote> portion of an email address.  For example, "
 1.13071 +"<quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> "
 1.13072 +"becomes <quote><literal>bos</literal></quote>."
 1.13073 +msgstr ""
 1.13074 +
 1.13075 +#. type: Content of: <book><chapter><sect1><note><para>
 1.13076 +#: ../en/ch11-template.xml:417
 1.13077 +msgid ""
 1.13078 +"If you try to apply a filter to a piece of data that it cannot process, "
 1.13079 +"Mercurial will fail and print a Python exception.  For example, trying to run "
 1.13080 +"the output of the <literal role=\"template-keyword\">desc</literal> keyword "
 1.13081 +"into the <literal role=\"template-kw-filt-date\">isodate</literal> filter is "
 1.13082 +"not a good idea."
 1.13083 +msgstr ""
 1.13084 +
 1.13085 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13086 +#: ../en/ch11-template.xml:426
 1.13087 +msgid "Combining filters"
 1.13088 +msgstr ""
 1.13089 +
 1.13090 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13091 +#: ../en/ch11-template.xml:428
 1.13092 +msgid ""
 1.13093 +"It is easy to combine filters to yield output in the form you would like.  "
 1.13094 +"The following chain of filters tidies up a description, then makes sure that "
 1.13095 +"it fits cleanly into 68 columns, then indents it by a further 8 characters "
 1.13096 +"(at least on Unix-like systems, where a tab is conventionally 8 characters "
 1.13097 +"wide)."
 1.13098 +msgstr ""
 1.13099 +
 1.13100 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13101 +#: ../en/ch11-template.xml:437
 1.13102 +msgid ""
 1.13103 +"Note the use of <quote><literal>\\t</literal></quote> (a tab character) in "
 1.13104 +"the template to force the first line to be indented; this is necessary since "
 1.13105 +"<literal role=\"template-keyword\">tabindent</literal> indents all lines "
 1.13106 +"<emphasis>except</emphasis> the first."
 1.13107 +msgstr ""
 1.13108 +
 1.13109 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13110 +#: ../en/ch11-template.xml:443
 1.13111 +msgid ""
 1.13112 +"Keep in mind that the order of filters in a chain is significant.  The first "
 1.13113 +"filter is applied to the result of the keyword; the second to the result of "
 1.13114 +"the first filter; and so on.  For example, using <literal>fill68|tabindent</"
 1.13115 +"literal> gives very different results from <literal>tabindent|fill68</"
 1.13116 +"literal>."
 1.13117 +msgstr ""
 1.13118 +
 1.13119 +#. type: Content of: <book><chapter><sect1><title>
 1.13120 +#: ../en/ch11-template.xml:454
 1.13121 +msgid "From templates to styles"
 1.13122 +msgstr ""
 1.13123 +
 1.13124 +#. type: Content of: <book><chapter><sect1><para>
 1.13125 +#: ../en/ch11-template.xml:456
 1.13126 +msgid ""
 1.13127 +"A command line template provides a quick and simple way to format some "
 1.13128 +"output.  Templates can become verbose, though, and it's useful to be able to "
 1.13129 +"give a template a name.  A style file is a template with a name, stored in a "
 1.13130 +"file."
 1.13131 +msgstr ""
 1.13132 +
 1.13133 +#. type: Content of: <book><chapter><sect1><para>
 1.13134 +#: ../en/ch11-template.xml:461
 1.13135 +msgid ""
 1.13136 +"More than that, using a style file unlocks the power of Mercurial's "
 1.13137 +"templating engine in ways that are not possible using the command line "
 1.13138 +"<option role=\"hg-opt-log\">--template</option> option."
 1.13139 +msgstr ""
 1.13140 +
 1.13141 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13142 +#: ../en/ch11-template.xml:467
 1.13143 +msgid "The simplest of style files"
 1.13144 +msgstr ""
 1.13145 +
 1.13146 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13147 +#: ../en/ch11-template.xml:469
 1.13148 +msgid "Our simple style file contains just one line:"
 1.13149 +msgstr ""
 1.13150 +
 1.13151 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13152 +#: ../en/ch11-template.xml:473
 1.13153 +msgid ""
 1.13154 +"This tells Mercurial, <quote>if you're printing a changeset, use the text on "
 1.13155 +"the right as the template</quote>."
 1.13156 +msgstr ""
 1.13157 +
 1.13158 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13159 +#: ../en/ch11-template.xml:479
 1.13160 +msgid "Style file syntax"
 1.13161 +msgstr ""
 1.13162 +
 1.13163 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13164 +#: ../en/ch11-template.xml:481
 1.13165 +msgid "The syntax rules for a style file are simple."
 1.13166 +msgstr ""
 1.13167 +
 1.13168 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13169 +#: ../en/ch11-template.xml:484
 1.13170 +msgid "The file is processed one line at a time."
 1.13171 +msgstr ""
 1.13172 +
 1.13173 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13174 +#: ../en/ch11-template.xml:487
 1.13175 +msgid "Leading and trailing white space are ignored."
 1.13176 +msgstr ""
 1.13177 +
 1.13178 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13179 +#: ../en/ch11-template.xml:490
 1.13180 +msgid "Empty lines are skipped."
 1.13181 +msgstr ""
 1.13182 +
 1.13183 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13184 +#: ../en/ch11-template.xml:492
 1.13185 +msgid ""
 1.13186 +"If a line starts with either of the characters <quote><literal>#</literal></"
 1.13187 +"quote> or <quote><literal>;</literal></quote>, the entire line is treated as "
 1.13188 +"a comment, and skipped as if empty."
 1.13189 +msgstr ""
 1.13190 +
 1.13191 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13192 +#: ../en/ch11-template.xml:497
 1.13193 +msgid ""
 1.13194 +"A line starts with a keyword.  This must start with an alphabetic character "
 1.13195 +"or underscore, and can subsequently contain any alphanumeric character or "
 1.13196 +"underscore.  (In regexp notation, a keyword must match <literal>[A-Za-z_][A-"
 1.13197 +"Za-z0-9_]*</literal>.)"
 1.13198 +msgstr ""
 1.13199 +
 1.13200 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13201 +#: ../en/ch11-template.xml:503
 1.13202 +msgid ""
 1.13203 +"The next element must be an <quote><literal>=</literal></quote> character, "
 1.13204 +"which can be preceded or followed by an arbitrary amount of white space."
 1.13205 +msgstr ""
 1.13206 +
 1.13207 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13208 +#: ../en/ch11-template.xml:508
 1.13209 +msgid ""
 1.13210 +"If the rest of the line starts and ends with matching quote characters "
 1.13211 +"(either single or double quote), it is treated as a template body."
 1.13212 +msgstr ""
 1.13213 +
 1.13214 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13215 +#: ../en/ch11-template.xml:512
 1.13216 +msgid ""
 1.13217 +"If the rest of the line <emphasis>does not</emphasis> start with a quote "
 1.13218 +"character, it is treated as the name of a file; the contents of this file "
 1.13219 +"will be read and used as a template body."
 1.13220 +msgstr ""
 1.13221 +
 1.13222 +#. type: Content of: <book><chapter><sect1><title>
 1.13223 +#: ../en/ch11-template.xml:521
 1.13224 +msgid "Style files by example"
 1.13225 +msgstr ""
 1.13226 +
 1.13227 +#. type: Content of: <book><chapter><sect1><para>
 1.13228 +#: ../en/ch11-template.xml:523
 1.13229 +msgid ""
 1.13230 +"To illustrate how to write a style file, we will construct a few by example.  "
 1.13231 +"Rather than provide a complete style file and walk through it, we'll mirror "
 1.13232 +"the usual process of developing a style file by starting with something very "
 1.13233 +"simple, and walking through a series of successively more complete examples."
 1.13234 +msgstr ""
 1.13235 +
 1.13236 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13237 +#: ../en/ch11-template.xml:530
 1.13238 +msgid "Identifying mistakes in style files"
 1.13239 +msgstr ""
 1.13240 +
 1.13241 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13242 +#: ../en/ch11-template.xml:532
 1.13243 +msgid ""
 1.13244 +"If Mercurial encounters a problem in a style file you are working on, it "
 1.13245 +"prints a terse error message that, once you figure out what it means, is "
 1.13246 +"actually quite useful."
 1.13247 +msgstr ""
 1.13248 +
 1.13249 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13250 +#: ../en/ch11-template.xml:538
 1.13251 +msgid ""
 1.13252 +"Notice that <filename>broken.style</filename> attempts to define a "
 1.13253 +"<literal>changeset</literal> keyword, but forgets to give any content for it. "
 1.13254 +"When instructed to use this style file, Mercurial promptly complains."
 1.13255 +msgstr ""
 1.13256 +
 1.13257 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13258 +#: ../en/ch11-template.xml:545
 1.13259 +msgid "This error message looks intimidating, but it is not too hard to follow."
 1.13260 +msgstr ""
 1.13261 +
 1.13262 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13263 +#: ../en/ch11-template.xml:549
 1.13264 +msgid ""
 1.13265 +"The first component is simply Mercurial's way of saying <quote>I am giving "
 1.13266 +"up</quote>."
 1.13267 +msgstr ""
 1.13268 +
 1.13269 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13270 +#: ../en/ch11-template.xml:554
 1.13271 +msgid "Next comes the name of the style file that contains the error."
 1.13272 +msgstr ""
 1.13273 +
 1.13274 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13275 +#: ../en/ch11-template.xml:560
 1.13276 +msgid ""
 1.13277 +"Following the file name is the line number where the error was encountered."
 1.13278 +msgstr ""
 1.13279 +
 1.13280 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13281 +#: ../en/ch11-template.xml:565
 1.13282 +msgid "Finally, a description of what went wrong."
 1.13283 +msgstr ""
 1.13284 +
 1.13285 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13286 +#: ../en/ch11-template.xml:570
 1.13287 +msgid ""
 1.13288 +"The description of the problem is not always clear (as in this case), but "
 1.13289 +"even when it is cryptic, it is almost always trivial to visually inspect the "
 1.13290 +"offending line in the style file and see what is wrong."
 1.13291 +msgstr ""
 1.13292 +
 1.13293 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13294 +#: ../en/ch11-template.xml:578
 1.13295 +msgid "Uniquely identifying a repository"
 1.13296 +msgstr ""
 1.13297 +
 1.13298 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13299 +#: ../en/ch11-template.xml:580
 1.13300 +msgid ""
 1.13301 +"If you would like to be able to identify a Mercurial repository <quote>fairly "
 1.13302 +"uniquely</quote> using a short string as an identifier, you can use the first "
 1.13303 +"revision in the repository."
 1.13304 +msgstr ""
 1.13305 +
 1.13306 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13307 +#: ../en/ch11-template.xml:587
 1.13308 +msgid ""
 1.13309 +"This is not guaranteed to be unique, but it is nevertheless useful in many "
 1.13310 +"cases."
 1.13311 +msgstr ""
 1.13312 +
 1.13313 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13314 +#: ../en/ch11-template.xml:590
 1.13315 +msgid ""
 1.13316 +"It will not work in a completely empty repository, because such a repository "
 1.13317 +"does not have a revision zero."
 1.13318 +msgstr ""
 1.13319 +
 1.13320 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13321 +#: ../en/ch11-template.xml:594
 1.13322 +msgid ""
 1.13323 +"Neither will it work in the (extremely rare)  case where a repository is a "
 1.13324 +"merge of two or more formerly independent repositories, and you still have "
 1.13325 +"those repositories around."
 1.13326 +msgstr ""
 1.13327 +
 1.13328 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13329 +#: ../en/ch11-template.xml:599
 1.13330 +msgid "Here are some uses to which you could put this identifier:"
 1.13331 +msgstr ""
 1.13332 +
 1.13333 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13334 +#: ../en/ch11-template.xml:602
 1.13335 +msgid ""
 1.13336 +"As a key into a table for a database that manages repositories on a server."
 1.13337 +msgstr ""
 1.13338 +
 1.13339 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13340 +#: ../en/ch11-template.xml:605
 1.13341 +msgid ""
 1.13342 +"As half of a {<emphasis>repository ID</emphasis>, <emphasis>revision ID</"
 1.13343 +"emphasis>} tuple.  Save this information away when you run an automated build "
 1.13344 +"or other activity, so that you can <quote>replay</quote> the build later if "
 1.13345 +"necessary."
 1.13346 +msgstr ""
 1.13347 +
 1.13348 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13349 +#: ../en/ch11-template.xml:614
 1.13350 +msgid "Mimicking Subversion's output"
 1.13351 +msgstr ""
 1.13352 +
 1.13353 +#
 1.13354 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13355 +#: ../en/ch11-template.xml:616
 1.13356 +msgid ""
 1.13357 +"Let's try to emulate the default output format used by another revision "
 1.13358 +"control tool, Subversion."
 1.13359 +msgstr ""
 1.13360 +
 1.13361 +#
 1.13362 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13363 +#: ../en/ch11-template.xml:621
 1.13364 +msgid ""
 1.13365 +"Since Subversion's output style is fairly simple, it is easy to copy-and-"
 1.13366 +"paste a hunk of its output into a file, and replace the text produced above "
 1.13367 +"by Subversion with the template values we'd like to see expanded."
 1.13368 +msgstr ""
 1.13369 +
 1.13370 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13371 +#: ../en/ch11-template.xml:628
 1.13372 +msgid ""
 1.13373 +"There are a few small ways in which this template deviates from the output "
 1.13374 +"produced by Subversion."
 1.13375 +msgstr ""
 1.13376 +
 1.13377 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13378 +#: ../en/ch11-template.xml:631
 1.13379 +msgid ""
 1.13380 +"Subversion prints a <quote>readable</quote> date (the <quote><literal>Wed, 27 "
 1.13381 +"Sep 2006</literal></quote> in the example output above) in parentheses.  "
 1.13382 +"Mercurial's templating engine does not provide a way to display a date in "
 1.13383 +"this format without also printing the time and time zone."
 1.13384 +msgstr ""
 1.13385 +
 1.13386 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13387 +#: ../en/ch11-template.xml:638
 1.13388 +msgid ""
 1.13389 +"We emulate Subversion's printing of <quote>separator</quote> lines full of "
 1.13390 +"<quote><literal>-</literal></quote> characters by ending the template with "
 1.13391 +"such a line. We use the templating engine's <literal role=\"template-keyword"
 1.13392 +"\">header</literal> keyword to print a separator line as the first line of "
 1.13393 +"output (see below), thus achieving similar output to Subversion."
 1.13394 +msgstr ""
 1.13395 +
 1.13396 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13397 +#: ../en/ch11-template.xml:647
 1.13398 +msgid ""
 1.13399 +"Subversion's output includes a count in the header of the number of lines in "
 1.13400 +"the commit message.  We cannot replicate this in Mercurial; the templating "
 1.13401 +"engine does not currently provide a filter that counts the number of lines "
 1.13402 +"the template generates."
 1.13403 +msgstr ""
 1.13404 +
 1.13405 +#
 1.13406 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13407 +#: ../en/ch11-template.xml:653
 1.13408 +msgid ""
 1.13409 +"It took me no more than a minute or two of work to replace literal text from "
 1.13410 +"an example of Subversion's output with some keywords and filters to give the "
 1.13411 +"template above.  The style file simply refers to the template."
 1.13412 +msgstr ""
 1.13413 +
 1.13414 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13415 +#: ../en/ch11-template.xml:660
 1.13416 +msgid ""
 1.13417 +"We could have included the text of the template file directly in the style "
 1.13418 +"file by enclosing it in quotes and replacing the newlines with "
 1.13419 +"<quote><literal>\\n</literal></quote> sequences, but it would have made the "
 1.13420 +"style file too difficult to read.  Readability is a good guide when you're "
 1.13421 +"trying to decide whether some text belongs in a style file, or in a template "
 1.13422 +"file that the style file points to.  If the style file will look too big or "
 1.13423 +"cluttered if you insert a literal piece of text, drop it into a template "
 1.13424 +"instead."
 1.13425 +msgstr ""
 1.13426 +
 1.13427 +#. type: Content of: <book><chapter><title>
 1.13428 +#: ../en/ch12-mq.xml:5
 1.13429 +msgid "Managing change with Mercurial Queues"
 1.13430 +msgstr "使用 MQ 管理修改"
 1.13431 +
 1.13432 +#. type: Content of: <book><chapter><sect1><title>
 1.13433 +#: ../en/ch12-mq.xml:8
 1.13434 +msgid "The patch management problem"
 1.13435 +msgstr ""
 1.13436 +
 1.13437 +#. type: Content of: <book><chapter><sect1><para>
 1.13438 +#: ../en/ch12-mq.xml:10
 1.13439 +msgid ""
 1.13440 +"Here is a common scenario: you need to install a software package from "
 1.13441 +"source, but you find a bug that you must fix in the source before you can "
 1.13442 +"start using the package.  You make your changes, forget about the package for "
 1.13443 +"a while, and a few months later you need to upgrade to a newer version of the "
 1.13444 +"package.  If the newer version of the package still has the bug, you must "
 1.13445 +"extract your fix from the older source tree and apply it against the newer "
 1.13446 +"version.  This is a tedious task, and it's easy to make mistakes."
 1.13447 +msgstr ""
 1.13448 +
 1.13449 +#. type: Content of: <book><chapter><sect1><para>
 1.13450 +#: ../en/ch12-mq.xml:20
 1.13451 +msgid ""
 1.13452 +"This is a simple case of the <quote>patch management</quote> problem.  You "
 1.13453 +"have an <quote>upstream</quote> source tree that you can't change; you need "
 1.13454 +"to make some local changes on top of the upstream tree; and you'd like to be "
 1.13455 +"able to keep those changes separate, so that you can apply them to newer "
 1.13456 +"versions of the upstream source."
 1.13457 +msgstr ""
 1.13458 +
 1.13459 +#. type: Content of: <book><chapter><sect1><para>
 1.13460 +#: ../en/ch12-mq.xml:27
 1.13461 +msgid ""
 1.13462 +"The patch management problem arises in many situations.  Probably the most "
 1.13463 +"visible is that a user of an open source software project will contribute a "
 1.13464 +"bug fix or new feature to the project's maintainers in the form of a patch."
 1.13465 +msgstr ""
 1.13466 +
 1.13467 +#. type: Content of: <book><chapter><sect1><para>
 1.13468 +#: ../en/ch12-mq.xml:32
 1.13469 +msgid ""
 1.13470 +"Distributors of operating systems that include open source software often "
 1.13471 +"need to make changes to the packages they distribute so that they will build "
 1.13472 +"properly in their environments."
 1.13473 +msgstr ""
 1.13474 +
 1.13475 +#. type: Content of: <book><chapter><sect1><para>
 1.13476 +#: ../en/ch12-mq.xml:37
 1.13477 +msgid ""
 1.13478 +"When you have few changes to maintain, it is easy to manage a single patch "
 1.13479 +"using the standard <command>diff</command> and <command>patch</command> "
 1.13480 +"programs (see section <xref linkend=\"sec.mq.patch\"/> for a discussion of "
 1.13481 +"these tools). Once the number of changes grows, it starts to make sense to "
 1.13482 +"maintain patches as discrete <quote>chunks of work,</quote> so that for "
 1.13483 +"example a single patch will contain only one bug fix (the patch might modify "
 1.13484 +"several files, but it's doing <quote>only one thing</quote>), and you may "
 1.13485 +"have a number of such patches for different bugs you need fixed and local "
 1.13486 +"changes you require.  In this situation, if you submit a bug fix patch to the "
 1.13487 +"upstream maintainers of a package and they include your fix in a subsequent "
 1.13488 +"release, you can simply drop that single patch when you're updating to the "
 1.13489 +"newer release."
 1.13490 +msgstr ""
 1.13491 +
 1.13492 +#. type: Content of: <book><chapter><sect1><para>
 1.13493 +#: ../en/ch12-mq.xml:52
 1.13494 +msgid ""
 1.13495 +"Maintaining a single patch against an upstream tree is a little tedious and "
 1.13496 +"error-prone, but not difficult.  However, the complexity of the problem grows "
 1.13497 +"rapidly as the number of patches you have to maintain increases.  With more "
 1.13498 +"than a tiny number of patches in hand, understanding which ones you have "
 1.13499 +"applied and maintaining them moves from messy to overwhelming."
 1.13500 +msgstr ""
 1.13501 +
 1.13502 +#. type: Content of: <book><chapter><sect1><para>
 1.13503 +#: ../en/ch12-mq.xml:59
 1.13504 +msgid ""
 1.13505 +"Fortunately, Mercurial includes a powerful extension, Mercurial Queues (or "
 1.13506 +"simply <quote>MQ</quote>), that massively simplifies the patch management "
 1.13507 +"problem."
 1.13508 +msgstr ""
 1.13509 +
 1.13510 +#. type: Content of: <book><chapter><sect1><title>
 1.13511 +#: ../en/ch12-mq.xml:65
 1.13512 +msgid "The prehistory of Mercurial Queues"
 1.13513 +msgstr ""
 1.13514 +
 1.13515 +#. type: Content of: <book><chapter><sect1><para>
 1.13516 +#: ../en/ch12-mq.xml:67
 1.13517 +msgid ""
 1.13518 +"During the late 1990s, several Linux kernel developers started to maintain "
 1.13519 +"<quote>patch series</quote> that modified the behaviour of the Linux kernel.  "
 1.13520 +"Some of these series were focused on stability, some on feature coverage, and "
 1.13521 +"others were more speculative."
 1.13522 +msgstr ""
 1.13523 +
 1.13524 +#. type: Content of: <book><chapter><sect1><para>
 1.13525 +#: ../en/ch12-mq.xml:73
 1.13526 +msgid ""
 1.13527 +"The sizes of these patch series grew rapidly.  In 2002, Andrew Morton "
 1.13528 +"published some shell scripts he had been using to automate the task of "
 1.13529 +"managing his patch queues.  Andrew was successfully using these scripts to "
 1.13530 +"manage hundreds (sometimes thousands) of patches on top of the Linux kernel."
 1.13531 +msgstr ""
 1.13532 +
 1.13533 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13534 +#: ../en/ch12-mq.xml:80
 1.13535 +msgid "A patchwork quilt"
 1.13536 +msgstr ""
 1.13537 +
 1.13538 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13539 +#: ../en/ch12-mq.xml:82
 1.13540 +msgid ""
 1.13541 +"In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the approach "
 1.13542 +"of Andrew's scripts and published a tool called <quote>patchwork quilt</"
 1.13543 +"quote> <citation>web:quilt</citation>, or simply <quote>quilt</quote> (see "
 1.13544 +"<citation>gruenbacher:2005</citation> for a paper describing it).  Because "
 1.13545 +"quilt substantially automated patch management, it rapidly gained a large "
 1.13546 +"following among open source software developers."
 1.13547 +msgstr ""
 1.13548 +
 1.13549 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13550 +#: ../en/ch12-mq.xml:91
 1.13551 +msgid ""
 1.13552 +"Quilt manages a <emphasis>stack of patches</emphasis> on top of a directory "
 1.13553 +"tree. To begin, you tell quilt to manage a directory tree, and tell it which "
 1.13554 +"files you want to manage; it stores away the names and contents of those "
 1.13555 +"files.  To fix a bug, you create a new patch (using a single command), edit "
 1.13556 +"the files you need to fix, then <quote>refresh</quote> the patch."
 1.13557 +msgstr ""
 1.13558 +
 1.13559 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13560 +#: ../en/ch12-mq.xml:99
 1.13561 +msgid ""
 1.13562 +"The refresh step causes quilt to scan the directory tree; it updates the "
 1.13563 +"patch with all of the changes you have made.  You can create another patch on "
 1.13564 +"top of the first, which will track the changes required to modify the tree "
 1.13565 +"from <quote>tree with one patch applied</quote> to <quote>tree with two "
 1.13566 +"patches applied</quote>."
 1.13567 +msgstr ""
 1.13568 +
 1.13569 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13570 +#: ../en/ch12-mq.xml:106
 1.13571 +msgid ""
 1.13572 +"You can <emphasis>change</emphasis> which patches are applied to the tree.  "
 1.13573 +"If you <quote>pop</quote> a patch, the changes made by that patch will vanish "
 1.13574 +"from the directory tree.  Quilt remembers which patches you have popped, "
 1.13575 +"though, so you can <quote>push</quote> a popped patch again, and the "
 1.13576 +"directory tree will be restored to contain the modifications in the patch.  "
 1.13577 +"Most importantly, you can run the <quote>refresh</quote> command at any time, "
 1.13578 +"and the topmost applied patch will be updated.  This means that you can, at "
 1.13579 +"any time, change both which patches are applied and what modifications those "
 1.13580 +"patches make."
 1.13581 +msgstr ""
 1.13582 +
 1.13583 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13584 +#: ../en/ch12-mq.xml:118
 1.13585 +msgid ""
 1.13586 +"Quilt knows nothing about revision control tools, so it works equally well on "
 1.13587 +"top of an unpacked tarball or a Subversion working copy."
 1.13588 +msgstr ""
 1.13589 +
 1.13590 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13591 +#: ../en/ch12-mq.xml:124
 1.13592 +msgid "From patchwork quilt to Mercurial Queues"
 1.13593 +msgstr ""
 1.13594 +
 1.13595 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13596 +#: ../en/ch12-mq.xml:126
 1.13597 +msgid ""
 1.13598 +"In mid-2005, Chris Mason took the features of quilt and wrote an extension "
 1.13599 +"that he called Mercurial Queues, which added quilt-like behaviour to "
 1.13600 +"Mercurial."
 1.13601 +msgstr ""
 1.13602 +
 1.13603 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13604 +#: ../en/ch12-mq.xml:130
 1.13605 +msgid ""
 1.13606 +"The key difference between quilt and MQ is that quilt knows nothing about "
 1.13607 +"revision control systems, while MQ is <emphasis>integrated</emphasis> into "
 1.13608 +"Mercurial.  Each patch that you push is represented as a Mercurial "
 1.13609 +"changeset.  Pop a patch, and the changeset goes away."
 1.13610 +msgstr ""
 1.13611 +
 1.13612 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13613 +#: ../en/ch12-mq.xml:136
 1.13614 +msgid ""
 1.13615 +"Because quilt does not care about revision control tools, it is still a "
 1.13616 +"tremendously useful piece of software to know about for situations where you "
 1.13617 +"cannot use Mercurial and MQ."
 1.13618 +msgstr ""
 1.13619 +
 1.13620 +#. type: Content of: <book><chapter><sect1><title>
 1.13621 +#: ../en/ch12-mq.xml:144
 1.13622 +msgid "The huge advantage of MQ"
 1.13623 +msgstr ""
 1.13624 +
 1.13625 +#. type: Content of: <book><chapter><sect1><para>
 1.13626 +#: ../en/ch12-mq.xml:146
 1.13627 +msgid ""
 1.13628 +"I cannot overstate the value that MQ offers through the unification of "
 1.13629 +"patches and revision control."
 1.13630 +msgstr ""
 1.13631 +
 1.13632 +#. type: Content of: <book><chapter><sect1><para>
 1.13633 +#: ../en/ch12-mq.xml:149
 1.13634 +msgid ""
 1.13635 +"A major reason that patches have persisted in the free software and open "
 1.13636 +"source world&emdash;in spite of the availability of increasingly capable "
 1.13637 +"revision control tools over the years&emdash;is the <emphasis>agility</"
 1.13638 +"emphasis> they offer."
 1.13639 +msgstr ""
 1.13640 +
 1.13641 +#. type: Content of: <book><chapter><sect1><para>
 1.13642 +#: ../en/ch12-mq.xml:155
 1.13643 +msgid ""
 1.13644 +"Traditional revision control tools make a permanent, irreversible record of "
 1.13645 +"everything that you do.  While this has great value, it's also somewhat "
 1.13646 +"stifling.  If you want to perform a wild-eyed experiment, you have to be "
 1.13647 +"careful in how you go about it, or you risk leaving unneeded&emdash;or worse, "
 1.13648 +"misleading or destabilising&emdash;traces of your missteps and errors in the "
 1.13649 +"permanent revision record."
 1.13650 +msgstr ""
 1.13651 +
 1.13652 +#. type: Content of: <book><chapter><sect1><para>
 1.13653 +#: ../en/ch12-mq.xml:163
 1.13654 +msgid ""
 1.13655 +"By contrast, MQ's marriage of distributed revision control with patches makes "
 1.13656 +"it much easier to isolate your work.  Your patches live on top of normal "
 1.13657 +"revision history, and you can make them disappear or reappear at will.  If "
 1.13658 +"you don't like a patch, you can drop it.  If a patch isn't quite as you want "
 1.13659 +"it to be, simply fix it&emdash;as many times as you need to, until you have "
 1.13660 +"refined it into the form you desire."
 1.13661 +msgstr ""
 1.13662 +
 1.13663 +#. type: Content of: <book><chapter><sect1><para>
 1.13664 +#: ../en/ch12-mq.xml:171
 1.13665 +msgid ""
 1.13666 +"As an example, the integration of patches with revision control makes "
 1.13667 +"understanding patches and debugging their effects&emdash;and their interplay "
 1.13668 +"with the code they're based on&emdash;<emphasis>enormously</emphasis> easier. "
 1.13669 +"Since every applied patch has an associated changeset, you can give <command "
 1.13670 +"role=\"hg-cmd\">hg log</command> a file name to see which changesets and "
 1.13671 +"patches affected the file.  You can use the <command role=\"hg-cmd\">hg "
 1.13672 +"bisect</command> command to binary-search through all changesets and applied "
 1.13673 +"patches to see where a bug got introduced or fixed.  You can use the <command "
 1.13674 +"role=\"hg-cmd\">hg annotate</command> command to see which changeset or patch "
 1.13675 +"modified a particular line of a source file.  And so on."
 1.13676 +msgstr ""
 1.13677 +
 1.13678 +#. type: Content of: <book><chapter><sect1><title>
 1.13679 +#: ../en/ch12-mq.xml:187
 1.13680 +msgid "Understanding patches"
 1.13681 +msgstr ""
 1.13682 +
 1.13683 +#. type: Content of: <book><chapter><sect1><para>
 1.13684 +#: ../en/ch12-mq.xml:189
 1.13685 +msgid ""
 1.13686 +"Because MQ doesn't hide its patch-oriented nature, it is helpful to "
 1.13687 +"understand what patches are, and a little about the tools that work with them."
 1.13688 +msgstr ""
 1.13689 +
 1.13690 +#. type: Content of: <book><chapter><sect1><para>
 1.13691 +#: ../en/ch12-mq.xml:193
 1.13692 +msgid ""
 1.13693 +"The traditional Unix <command>diff</command> command compares two files, and "
 1.13694 +"prints a list of differences between them. The <command>patch</command> "
 1.13695 +"command understands these differences as <emphasis>modifications</emphasis> "
 1.13696 +"to make to a file.  Take a look below for a simple example of these commands "
 1.13697 +"in action."
 1.13698 +msgstr ""
 1.13699 +
 1.13700 +#. type: Content of: <book><chapter><sect1><para>
 1.13701 +#: ../en/ch12-mq.xml:202
 1.13702 +msgid ""
 1.13703 +"The type of file that <command>diff</command> generates (and <command>patch</"
 1.13704 +"command> takes as input) is called a <quote>patch</quote> or a <quote>diff</"
 1.13705 +"quote>; there is no difference between a patch and a diff.  (We'll use the "
 1.13706 +"term <quote>patch</quote>, since it's more commonly used.)"
 1.13707 +msgstr ""
 1.13708 +
 1.13709 +#. type: Content of: <book><chapter><sect1><para>
 1.13710 +#: ../en/ch12-mq.xml:208
 1.13711 +msgid ""
 1.13712 +"A patch file can start with arbitrary text; the <command>patch</command> "
 1.13713 +"command ignores this text, but MQ uses it as the commit message when creating "
 1.13714 +"changesets.  To find the beginning of the patch content, <command>patch</"
 1.13715 +"command> searches for the first line that starts with the string "
 1.13716 +"<quote><literal>diff -</literal></quote>."
 1.13717 +msgstr ""
 1.13718 +
 1.13719 +#. type: Content of: <book><chapter><sect1><para>
 1.13720 +#: ../en/ch12-mq.xml:215
 1.13721 +msgid ""
 1.13722 +"MQ works with <emphasis>unified</emphasis> diffs (<command>patch</command> "
 1.13723 +"can accept several other diff formats, but MQ doesn't).  A unified diff "
 1.13724 +"contains two kinds of header.  The <emphasis>file header</emphasis> describes "
 1.13725 +"the file being modified; it contains the name of the file to modify.  When "
 1.13726 +"<command>patch</command> sees a new file header, it looks for a file with "
 1.13727 +"that name to start modifying."
 1.13728 +msgstr ""
 1.13729 +
 1.13730 +#. type: Content of: <book><chapter><sect1><para>
 1.13731 +#: ../en/ch12-mq.xml:223
 1.13732 +msgid ""
 1.13733 +"After the file header comes a series of <emphasis>hunks</emphasis>.  Each "
 1.13734 +"hunk starts with a header; this identifies the range of line numbers within "
 1.13735 +"the file that the hunk should modify.  Following the header, a hunk starts "
 1.13736 +"and ends with a few (usually three) lines of text from the unmodified file; "
 1.13737 +"these are called the <emphasis>context</emphasis> for the hunk.  If there's "
 1.13738 +"only a small amount of context between successive hunks, <command>diff</"
 1.13739 +"command> doesn't print a new hunk header; it just runs the hunks together, "
 1.13740 +"with a few lines of context between modifications."
 1.13741 +msgstr ""
 1.13742 +
 1.13743 +#. type: Content of: <book><chapter><sect1><para>
 1.13744 +#: ../en/ch12-mq.xml:235
 1.13745 +msgid ""
 1.13746 +"Each line of context begins with a space character.  Within the hunk, a line "
 1.13747 +"that begins with <quote><literal>-</literal></quote> means <quote>remove this "
 1.13748 +"line,</quote> while a line that begins with <quote><literal>+</literal></"
 1.13749 +"quote> means <quote>insert this line.</quote> For example, a line that is "
 1.13750 +"modified is represented by one deletion and one insertion."
 1.13751 +msgstr ""
 1.13752 +
 1.13753 +#. type: Content of: <book><chapter><sect1><para>
 1.13754 +#: ../en/ch12-mq.xml:243
 1.13755 +msgid ""
 1.13756 +"We will return to some of the more subtle aspects of patches later (in "
 1.13757 +"section <xref linkend=\"sec.mq.adv-patch\"/>), but you should have enough "
 1.13758 +"information now to use MQ."
 1.13759 +msgstr ""
 1.13760 +
 1.13761 +#. type: Content of: <book><chapter><sect1><title>
 1.13762 +#: ../en/ch12-mq.xml:250
 1.13763 +msgid "Getting started with Mercurial Queues"
 1.13764 +msgstr ""
 1.13765 +
 1.13766 +#. type: Content of: <book><chapter><sect1><para>
 1.13767 +#: ../en/ch12-mq.xml:252
 1.13768 +msgid ""
 1.13769 +"Because MQ is implemented as an extension, you must explicitly enable before "
 1.13770 +"you can use it.  (You don't need to download anything; MQ ships with the "
 1.13771 +"standard Mercurial distribution.)  To enable MQ, edit your <filename role="
 1.13772 +"\"home\">~/.hgrc</filename> file, and add the lines below."
 1.13773 +msgstr ""
 1.13774 +
 1.13775 +#. type: Content of: <book><chapter><sect1><para>
 1.13776 +#: ../en/ch12-mq.xml:261
 1.13777 +msgid ""
 1.13778 +"Once the extension is enabled, it will make a number of new commands "
 1.13779 +"available.  To verify that the extension is working, you can use <command "
 1.13780 +"role=\"hg-cmd\">hg help</command> to see if the <command role=\"hg-ext-mq"
 1.13781 +"\">qinit</command> command is now available."
 1.13782 +msgstr ""
 1.13783 +
 1.13784 +#. type: Content of: <book><chapter><sect1><para>
 1.13785 +#: ../en/ch12-mq.xml:269
 1.13786 +msgid ""
 1.13787 +"You can use MQ with <emphasis>any</emphasis> Mercurial repository, and its "
 1.13788 +"commands only operate within that repository.  To get started, simply prepare "
 1.13789 +"the repository using the <command role=\"hg-ext-mq\">qinit</command> command."
 1.13790 +msgstr ""
 1.13791 +
 1.13792 +#. type: Content of: <book><chapter><sect1><para>
 1.13793 +#: ../en/ch12-mq.xml:276
 1.13794 +msgid ""
 1.13795 +"This command creates an empty directory called <filename role=\"special\" "
 1.13796 +"class=\"directory\">.hg/patches</filename>, where MQ will keep its metadata.  "
 1.13797 +"As with many Mercurial commands, the <command role=\"hg-ext-mq\">qinit</"
 1.13798 +"command> command prints nothing if it succeeds."
 1.13799 +msgstr ""
 1.13800 +
 1.13801 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13802 +#: ../en/ch12-mq.xml:283
 1.13803 +msgid "Creating a new patch"
 1.13804 +msgstr ""
 1.13805 +
 1.13806 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13807 +#: ../en/ch12-mq.xml:285
 1.13808 +msgid ""
 1.13809 +"To begin work on a new patch, use the <command role=\"hg-ext-mq\">qnew</"
 1.13810 +"command> command.  This command takes one argument, the name of the patch to "
 1.13811 +"create."
 1.13812 +msgstr ""
 1.13813 +
 1.13814 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13815 +#: ../en/ch12-mq.xml:289
 1.13816 +msgid ""
 1.13817 +"MQ will use this as the name of an actual file in the <filename role=\"special"
 1.13818 +"\" class=\"directory\">.hg/patches</filename> directory, as you can see below."
 1.13819 +msgstr ""
 1.13820 +
 1.13821 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13822 +#: ../en/ch12-mq.xml:296
 1.13823 +msgid ""
 1.13824 +"Also newly present in the <filename role=\"special\" class=\"directory\">.hg/"
 1.13825 +"patches</filename> directory are two other files, <filename role=\"special"
 1.13826 +"\">series</filename> and <filename role=\"special\">status</filename>.  The "
 1.13827 +"<filename role=\"special\">series</filename> file lists all of the patches "
 1.13828 +"that MQ knows about for this repository, with one patch per line.  Mercurial "
 1.13829 +"uses the <filename role=\"special\">status</filename> file for internal book-"
 1.13830 +"keeping; it tracks all of the patches that MQ has <emphasis>applied</"
 1.13831 +"emphasis> in this repository."
 1.13832 +msgstr ""
 1.13833 +
 1.13834 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
 1.13835 +#: ../en/ch12-mq.xml:308
 1.13836 +msgid ""
 1.13837 +"You may sometimes want to edit the <filename role=\"special\">series</"
 1.13838 +"filename> file by hand; for example, to change the sequence in which some "
 1.13839 +"patches are applied.  However, manually editing the <filename role=\"special"
 1.13840 +"\">status</filename> file is almost always a bad idea, as it's easy to "
 1.13841 +"corrupt MQ's idea of what is happening."
 1.13842 +msgstr ""
 1.13843 +
 1.13844 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13845 +#: ../en/ch12-mq.xml:317
 1.13846 +msgid ""
 1.13847 +"Once you have created your new patch, you can edit files in the working "
 1.13848 +"directory as you usually would.  All of the normal Mercurial commands, such "
 1.13849 +"as <command role=\"hg-cmd\">hg diff</command> and <command role=\"hg-cmd\">hg "
 1.13850 +"annotate</command>, work exactly as they did before."
 1.13851 +msgstr ""
 1.13852 +
 1.13853 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13854 +#: ../en/ch12-mq.xml:325
 1.13855 +msgid "Refreshing a patch"
 1.13856 +msgstr ""
 1.13857 +
 1.13858 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13859 +#: ../en/ch12-mq.xml:327
 1.13860 +msgid ""
 1.13861 +"When you reach a point where you want to save your work, use the <command "
 1.13862 +"role=\"hg-ext-mq\">qrefresh</command> command to update the patch you are "
 1.13863 +"working on."
 1.13864 +msgstr ""
 1.13865 +
 1.13866 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13867 +#: ../en/ch12-mq.xml:333
 1.13868 +msgid ""
 1.13869 +"This command folds the changes you have made in the working directory into "
 1.13870 +"your patch, and updates its corresponding changeset to contain those changes."
 1.13871 +msgstr ""
 1.13872 +
 1.13873 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13874 +#: ../en/ch12-mq.xml:337
 1.13875 +msgid ""
 1.13876 +"You can run <command role=\"hg-ext-mq\">qrefresh</command> as often as you "
 1.13877 +"like, so it's a good way to <quote>checkpoint</quote> your work.  Refresh "
 1.13878 +"your patch at an opportune time; try an experiment; and if the experiment "
 1.13879 +"doesn't work out, <command role=\"hg-cmd\">hg revert</command> your "
 1.13880 +"modifications back to the last time you refreshed."
 1.13881 +msgstr ""
 1.13882 +
 1.13883 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13884 +#: ../en/ch12-mq.xml:348
 1.13885 +msgid "Stacking and tracking patches"
 1.13886 +msgstr ""
 1.13887 +
 1.13888 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13889 +#: ../en/ch12-mq.xml:350
 1.13890 +msgid ""
 1.13891 +"Once you have finished working on a patch, or need to work on another, you "
 1.13892 +"can use the <command role=\"hg-ext-mq\">qnew</command> command again to "
 1.13893 +"create a new patch. Mercurial will apply this patch on top of your existing "
 1.13894 +"patch."
 1.13895 +msgstr ""
 1.13896 +
 1.13897 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13898 +#: ../en/ch12-mq.xml:357
 1.13899 +msgid ""
 1.13900 +"Notice that the patch contains the changes in our prior patch as part of its "
 1.13901 +"context (you can see this more clearly in the output of <command role=\"hg-cmd"
 1.13902 +"\">hg annotate</command>)."
 1.13903 +msgstr ""
 1.13904 +
 1.13905 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13906 +#: ../en/ch12-mq.xml:362
 1.13907 +msgid ""
 1.13908 +"So far, with the exception of <command role=\"hg-ext-mq\">qnew</command> and "
 1.13909 +"<command role=\"hg-ext-mq\">qrefresh</command>, we've been careful to only "
 1.13910 +"use regular Mercurial commands.  However, MQ provides many commands that are "
 1.13911 +"easier to use when you are thinking about patches, as illustrated below."
 1.13912 +msgstr ""
 1.13913 +
 1.13914 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13915 +#: ../en/ch12-mq.xml:372
 1.13916 +msgid ""
 1.13917 +"The <command role=\"hg-ext-mq\">qseries</command> command lists every patch "
 1.13918 +"that MQ knows about in this repository, from oldest to newest (most recently "
 1.13919 +"<emphasis>created</emphasis>)."
 1.13920 +msgstr ""
 1.13921 +
 1.13922 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.13923 +#: ../en/ch12-mq.xml:378
 1.13924 +msgid ""
 1.13925 +"The <command role=\"hg-ext-mq\">qapplied</command> command lists every patch "
 1.13926 +"that MQ has <emphasis>applied</emphasis> in this repository, again from "
 1.13927 +"oldest to newest (most recently applied)."
 1.13928 +msgstr ""
 1.13929 +
 1.13930 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13931 +#: ../en/ch12-mq.xml:387
 1.13932 +msgid "Manipulating the patch stack"
 1.13933 +msgstr ""
 1.13934 +
 1.13935 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13936 +#: ../en/ch12-mq.xml:389
 1.13937 +msgid ""
 1.13938 +"The previous discussion implied that there must be a difference between "
 1.13939 +"<quote>known</quote> and <quote>applied</quote> patches, and there is.  MQ "
 1.13940 +"can manage a patch without it being applied in the repository."
 1.13941 +msgstr ""
 1.13942 +
 1.13943 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13944 +#: ../en/ch12-mq.xml:394
 1.13945 +msgid ""
 1.13946 +"An <emphasis>applied</emphasis> patch has a corresponding changeset in the "
 1.13947 +"repository, and the effects of the patch and changeset are visible in the "
 1.13948 +"working directory.  You can undo the application of a patch using the "
 1.13949 +"<command role=\"hg-ext-mq\">qpop</command> command.  MQ still <emphasis>knows "
 1.13950 +"about</emphasis>, or manages, a popped patch, but the patch no longer has a "
 1.13951 +"corresponding changeset in the repository, and the working directory does not "
 1.13952 +"contain the changes made by the patch.  Figure <xref linkend=\"fig.mq.stack\"/"
 1.13953 +"> illustrates the difference between applied and tracked patches."
 1.13954 +msgstr ""
 1.13955 +
 1.13956 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject>
 1.13957 +#: ../en/ch12-mq.xml:407
 1.13958 +msgid "<imageobject><imagedata fileref=\"images/mq-stack.png\"/></imageobject>"
 1.13959 +msgstr ""
 1.13960 +
 1.13961 +#. type: Content of: <book><chapter><sect1><sect2><informalfigure><mediaobject><caption><para>
 1.13962 +#: ../en/ch12-mq.xml:409
 1.13963 +msgid "Applied and unapplied patches in the MQ patch stack"
 1.13964 +msgstr ""
 1.13965 +
 1.13966 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13967 +#: ../en/ch12-mq.xml:414
 1.13968 +msgid ""
 1.13969 +"You can reapply an unapplied, or popped, patch using the <command role=\"hg-"
 1.13970 +"ext-mq\">qpush</command> command.  This creates a new changeset to correspond "
 1.13971 +"to the patch, and the patch's changes once again become present in the "
 1.13972 +"working directory.  See below for examples of <command role=\"hg-ext-mq"
 1.13973 +"\">qpop</command> and <command role=\"hg-ext-mq\">qpush</command> in action."
 1.13974 +msgstr ""
 1.13975 +
 1.13976 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13977 +#: ../en/ch12-mq.xml:423
 1.13978 +msgid ""
 1.13979 +"Notice that once we have popped a patch or two patches, the output of "
 1.13980 +"<command role=\"hg-ext-mq\">qseries</command> remains the same, while that of "
 1.13981 +"<command role=\"hg-ext-mq\">qapplied</command> has changed."
 1.13982 +msgstr ""
 1.13983 +
 1.13984 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.13985 +#: ../en/ch12-mq.xml:431
 1.13986 +msgid "Pushing and popping many patches"
 1.13987 +msgstr ""
 1.13988 +
 1.13989 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.13990 +#: ../en/ch12-mq.xml:433
 1.13991 +msgid ""
 1.13992 +"While <command role=\"hg-ext-mq\">qpush</command> and <command role=\"hg-ext-"
 1.13993 +"mq\">qpop</command> each operate on a single patch at a time by default, you "
 1.13994 +"can push and pop many patches in one go.  The <option role=\"hg-ext-mq-cmd-"
 1.13995 +"qpush-opt\">hg -a</option> option to <command role=\"hg-ext-mq\">qpush</"
 1.13996 +"command> causes it to push all unapplied patches, while the <option role=\"hg-"
 1.13997 +"ext-mq-cmd-qpop-opt\">-a</option> option to <command role=\"hg-ext-mq\">qpop</"
 1.13998 +"command> causes it to pop all applied patches.  (For some more ways to push "
 1.13999 +"and pop many patches, see section <xref linkend=\"sec.mq.perf\"/> below.)"
 1.14000 +msgstr ""
 1.14001 +
 1.14002 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14003 +#: ../en/ch12-mq.xml:450
 1.14004 +msgid "Safety checks, and overriding them"
 1.14005 +msgstr ""
 1.14006 +
 1.14007 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14008 +#: ../en/ch12-mq.xml:452
 1.14009 +msgid ""
 1.14010 +"Several MQ commands check the working directory before they do anything, and "
 1.14011 +"fail if they find any modifications.  They do this to ensure that you won't "
 1.14012 +"lose any changes that you have made, but not yet incorporated into a patch.  "
 1.14013 +"The example below illustrates this; the <command role=\"hg-ext-mq\">qnew</"
 1.14014 +"command> command will not create a new patch if there are outstanding "
 1.14015 +"changes, caused in this case by the <command role=\"hg-cmd\">hg add</command> "
 1.14016 +"of <filename>file3</filename>."
 1.14017 +msgstr ""
 1.14018 +
 1.14019 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14020 +#: ../en/ch12-mq.xml:464
 1.14021 +msgid ""
 1.14022 +"Commands that check the working directory all take an <quote>I know what I'm "
 1.14023 +"doing</quote> option, which is always named <option>-f</option>.  The exact "
 1.14024 +"meaning of <option>-f</option> depends on the command.  For example, <command "
 1.14025 +"role=\"hg-cmd\">hg qnew <option role=\"hg-ext-mq-cmd-qnew-opt\">hg -f</"
 1.14026 +"option></command> will incorporate any outstanding changes into the new patch "
 1.14027 +"it creates, but <command role=\"hg-cmd\">hg qpop <option role=\"hg-ext-mq-cmd-"
 1.14028 +"qpop-opt\">hg -f</option></command> will revert modifications to any files "
 1.14029 +"affected by the patch that it is popping.  Be sure to read the documentation "
 1.14030 +"for a command's <option>-f</option> option before you use it!"
 1.14031 +msgstr ""
 1.14032 +
 1.14033 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14034 +#: ../en/ch12-mq.xml:479
 1.14035 +msgid "Working on several patches at once"
 1.14036 +msgstr ""
 1.14037 +
 1.14038 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14039 +#: ../en/ch12-mq.xml:481
 1.14040 +msgid ""
 1.14041 +"The <command role=\"hg-ext-mq\">qrefresh</command> command always refreshes "
 1.14042 +"the <emphasis>topmost</emphasis> applied patch.  This means that you can "
 1.14043 +"suspend work on one patch (by refreshing it), pop or push to make a different "
 1.14044 +"patch the top, and work on <emphasis>that</emphasis> patch for a while."
 1.14045 +msgstr ""
 1.14046 +
 1.14047 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14048 +#: ../en/ch12-mq.xml:488
 1.14049 +msgid ""
 1.14050 +"Here's an example that illustrates how you can use this ability. Let's say "
 1.14051 +"you're developing a new feature as two patches.  The first is a change to the "
 1.14052 +"core of your software, and the second&emdash;layered on top of the "
 1.14053 +"first&emdash;changes the user interface to use the code you just added to the "
 1.14054 +"core.  If you notice a bug in the core while you're working on the UI patch, "
 1.14055 +"it's easy to fix the core.  Simply <command role=\"hg-ext-mq\">qrefresh</"
 1.14056 +"command> the UI patch to save your in-progress changes, and <command role="
 1.14057 +"\"hg-ext-mq\">qpop</command> down to the core patch.  Fix the core bug, "
 1.14058 +"<command role=\"hg-ext-mq\">qrefresh</command> the core patch, and <command "
 1.14059 +"role=\"hg-ext-mq\">qpush</command> back to the UI patch to continue where you "
 1.14060 +"left off."
 1.14061 +msgstr ""
 1.14062 +
 1.14063 +#. type: Content of: <book><chapter><sect1><title>
 1.14064 +#: ../en/ch12-mq.xml:505
 1.14065 +msgid "More about patches"
 1.14066 +msgstr ""
 1.14067 +
 1.14068 +#. type: Content of: <book><chapter><sect1><para>
 1.14069 +#: ../en/ch12-mq.xml:507
 1.14070 +msgid ""
 1.14071 +"MQ uses the GNU <command>patch</command> command to apply patches, so it's "
 1.14072 +"helpful to know a few more detailed aspects of how <command>patch</command> "
 1.14073 +"works, and about patches themselves."
 1.14074 +msgstr ""
 1.14075 +
 1.14076 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14077 +#: ../en/ch12-mq.xml:513
 1.14078 +msgid "The strip count"
 1.14079 +msgstr ""
 1.14080 +
 1.14081 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14082 +#: ../en/ch12-mq.xml:515
 1.14083 +msgid ""
 1.14084 +"If you look at the file headers in a patch, you will notice that the "
 1.14085 +"pathnames usually have an extra component on the front that isn't present in "
 1.14086 +"the actual path name.  This is a holdover from the way that people used to "
 1.14087 +"generate patches (people still do this, but it's somewhat rare with modern "
 1.14088 +"revision control tools)."
 1.14089 +msgstr ""
 1.14090 +
 1.14091 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14092 +#: ../en/ch12-mq.xml:522
 1.14093 +msgid ""
 1.14094 +"Alice would unpack a tarball, edit her files, then decide that she wanted to "
 1.14095 +"create a patch.  So she'd rename her working directory, unpack the tarball "
 1.14096 +"again (hence the need for the rename), and use the <option role=\"cmd-opt-diff"
 1.14097 +"\">-r</option> and <option role=\"cmd-opt-diff\">-N</option> options to "
 1.14098 +"<command>diff</command> to recursively generate a patch between the "
 1.14099 +"unmodified directory and the modified one.  The result would be that the name "
 1.14100 +"of the unmodified directory would be at the front of the left-hand path in "
 1.14101 +"every file header, and the name of the modified directory would be at the "
 1.14102 +"front of the right-hand path."
 1.14103 +msgstr ""
 1.14104 +
 1.14105 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14106 +#: ../en/ch12-mq.xml:535
 1.14107 +msgid ""
 1.14108 +"Since someone receiving a patch from the Alices of the net would be unlikely "
 1.14109 +"to have unmodified and modified directories with exactly the same names, the "
 1.14110 +"<command>patch</command> command has a <option role=\"cmd-opt-patch\">-p</"
 1.14111 +"option> option that indicates the number of leading path name components to "
 1.14112 +"strip when trying to apply a patch.  This number is called the "
 1.14113 +"<emphasis>strip count</emphasis>."
 1.14114 +msgstr ""
 1.14115 +
 1.14116 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14117 +#: ../en/ch12-mq.xml:543
 1.14118 +msgid ""
 1.14119 +"An option of <quote><literal>-p1</literal></quote> means <quote>use a strip "
 1.14120 +"count of one</quote>.  If <command>patch</command> sees a file name "
 1.14121 +"<filename>foo/bar/baz</filename> in a file header, it will strip "
 1.14122 +"<filename>foo</filename> and try to patch a file named <filename>bar/baz</"
 1.14123 +"filename>.  (Strictly speaking, the strip count refers to the number of "
 1.14124 +"<emphasis>path separators</emphasis> (and the components that go with them ) "
 1.14125 +"to strip.  A strip count of one will turn <filename>foo/bar</filename> into "
 1.14126 +"<filename>bar</filename>, but <filename>/foo/bar</filename> (notice the extra "
 1.14127 +"leading slash) into <filename>foo/bar</filename>.)"
 1.14128 +msgstr ""
 1.14129 +
 1.14130 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14131 +#: ../en/ch12-mq.xml:556
 1.14132 +msgid ""
 1.14133 +"The <quote>standard</quote> strip count for patches is one; almost all "
 1.14134 +"patches contain one leading path name component that needs to be stripped. "
 1.14135 +"Mercurial's <command role=\"hg-cmd\">hg diff</command> command generates path "
 1.14136 +"names in this form, and the <command role=\"hg-cmd\">hg import</command> "
 1.14137 +"command and MQ expect patches to have a strip count of one."
 1.14138 +msgstr ""
 1.14139 +
 1.14140 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14141 +#: ../en/ch12-mq.xml:564
 1.14142 +msgid ""
 1.14143 +"If you receive a patch from someone that you want to add to your patch queue, "
 1.14144 +"and the patch needs a strip count other than one, you cannot just <command "
 1.14145 +"role=\"hg-ext-mq\">qimport</command> the patch, because <command role=\"hg-"
 1.14146 +"ext-mq\">qimport</command> does not yet have a <literal>-p</literal> option "
 1.14147 +"(see <ulink role=\"hg-bug\" url=\"http://www.selenic.com/mercurial/bts/"
 1.14148 +"issue311\">issue 311</ulink>).  Your best bet is to <command role=\"hg-ext-mq"
 1.14149 +"\">qnew</command> a patch of your own, then use <command>patch -pN</command> "
 1.14150 +"to apply their patch, followed by <command role=\"hg-cmd\">hg addremove</"
 1.14151 +"command> to pick up any files added or removed by the patch, followed by "
 1.14152 +"<command role=\"hg-ext-mq\">hg qrefresh</command>. This complexity may become "
 1.14153 +"unnecessary; see <ulink role=\"hg-bug\" url=\"http://www.selenic.com/"
 1.14154 +"mercurial/bts/issue311\">issue 311</ulink> for details."
 1.14155 +msgstr ""
 1.14156 +
 1.14157 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14158 +#: ../en/ch12-mq.xml:583
 1.14159 +msgid "Strategies for applying a patch"
 1.14160 +msgstr ""
 1.14161 +
 1.14162 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14163 +#: ../en/ch12-mq.xml:585
 1.14164 +msgid ""
 1.14165 +"When <command>patch</command> applies a hunk, it tries a handful of "
 1.14166 +"successively less accurate strategies to try to make the hunk apply. This "
 1.14167 +"falling-back technique often makes it possible to take a patch that was "
 1.14168 +"generated against an old version of a file, and apply it against a newer "
 1.14169 +"version of that file."
 1.14170 +msgstr ""
 1.14171 +
 1.14172 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14173 +#: ../en/ch12-mq.xml:592
 1.14174 +msgid ""
 1.14175 +"First, <command>patch</command> tries an exact match, where the line numbers, "
 1.14176 +"the context, and the text to be modified must apply exactly.  If it cannot "
 1.14177 +"make an exact match, it tries to find an exact match for the context, without "
 1.14178 +"honouring the line numbering information.  If this succeeds, it prints a line "
 1.14179 +"of output saying that the hunk was applied, but at some <emphasis>offset</"
 1.14180 +"emphasis> from the original line number."
 1.14181 +msgstr ""
 1.14182 +
 1.14183 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14184 +#: ../en/ch12-mq.xml:601
 1.14185 +msgid ""
 1.14186 +"If a context-only match fails, <command>patch</command> removes the first and "
 1.14187 +"last lines of the context, and tries a <emphasis>reduced</emphasis> context-"
 1.14188 +"only match.  If the hunk with reduced context succeeds, it prints a message "
 1.14189 +"saying that it applied the hunk with a <emphasis>fuzz factor</emphasis> (the "
 1.14190 +"number after the fuzz factor indicates how many lines of context "
 1.14191 +"<command>patch</command> had to trim before the patch applied)."
 1.14192 +msgstr ""
 1.14193 +
 1.14194 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14195 +#: ../en/ch12-mq.xml:610
 1.14196 +msgid ""
 1.14197 +"When neither of these techniques works, <command>patch</command> prints a "
 1.14198 +"message saying that the hunk in question was rejected.  It saves rejected "
 1.14199 +"hunks (also simply called <quote>rejects</quote>) to a file with the same "
 1.14200 +"name, and an added <filename role=\"special\">.rej</filename> extension.  It "
 1.14201 +"also saves an unmodified copy of the file with a <filename role=\"special\">."
 1.14202 +"orig</filename> extension; the copy of the file without any extensions will "
 1.14203 +"contain any changes made by hunks that <emphasis>did</emphasis> apply "
 1.14204 +"cleanly.  If you have a patch that modifies <filename>foo</filename> with six "
 1.14205 +"hunks, and one of them fails to apply, you will have: an unmodified "
 1.14206 +"<filename>foo.orig</filename>, a <filename>foo.rej</filename> containing one "
 1.14207 +"hunk, and <filename>foo</filename>, containing the changes made by the five "
 1.14208 +"successful hunks."
 1.14209 +msgstr ""
 1.14210 +
 1.14211 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14212 +#: ../en/ch12-mq.xml:628
 1.14213 +msgid "Some quirks of patch representation"
 1.14214 +msgstr ""
 1.14215 +
 1.14216 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14217 +#: ../en/ch12-mq.xml:630
 1.14218 +msgid ""
 1.14219 +"There are a few useful things to know about how <command>patch</command> "
 1.14220 +"works with files."
 1.14221 +msgstr ""
 1.14222 +
 1.14223 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14224 +#: ../en/ch12-mq.xml:633
 1.14225 +msgid ""
 1.14226 +"This should already be obvious, but <command>patch</command> cannot handle "
 1.14227 +"binary files."
 1.14228 +msgstr ""
 1.14229 +
 1.14230 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14231 +#: ../en/ch12-mq.xml:637
 1.14232 +msgid ""
 1.14233 +"Neither does it care about the executable bit; it creates new files as "
 1.14234 +"readable, but not executable."
 1.14235 +msgstr ""
 1.14236 +
 1.14237 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14238 +#: ../en/ch12-mq.xml:641
 1.14239 +msgid ""
 1.14240 +"<command>patch</command> treats the removal of a file as a diff between the "
 1.14241 +"file to be removed and the empty file.  So your idea of <quote>I deleted this "
 1.14242 +"file</quote> looks like <quote>every line of this file was deleted</quote> in "
 1.14243 +"a patch."
 1.14244 +msgstr ""
 1.14245 +
 1.14246 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14247 +#: ../en/ch12-mq.xml:647
 1.14248 +msgid ""
 1.14249 +"It treats the addition of a file as a diff between the empty file and the "
 1.14250 +"file to be added.  So in a patch, your idea of <quote>I added this file</"
 1.14251 +"quote> looks like <quote>every line of this file was added</quote>."
 1.14252 +msgstr ""
 1.14253 +
 1.14254 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14255 +#: ../en/ch12-mq.xml:653
 1.14256 +msgid ""
 1.14257 +"It treats a renamed file as the removal of the old name, and the addition of "
 1.14258 +"the new name.  This means that renamed files have a big footprint in "
 1.14259 +"patches.  (Note also that Mercurial does not currently try to infer when "
 1.14260 +"files have been renamed or copied in a patch.)"
 1.14261 +msgstr ""
 1.14262 +
 1.14263 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14264 +#: ../en/ch12-mq.xml:659
 1.14265 +msgid ""
 1.14266 +"<command>patch</command> cannot represent empty files, so you cannot use a "
 1.14267 +"patch to represent the notion <quote>I added this empty file to the tree</"
 1.14268 +"quote>."
 1.14269 +msgstr ""
 1.14270 +
 1.14271 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14272 +#: ../en/ch12-mq.xml:666
 1.14273 +msgid "Beware the fuzz"
 1.14274 +msgstr ""
 1.14275 +
 1.14276 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14277 +#: ../en/ch12-mq.xml:668
 1.14278 +msgid ""
 1.14279 +"While applying a hunk at an offset, or with a fuzz factor, will often be "
 1.14280 +"completely successful, these inexact techniques naturally leave open the "
 1.14281 +"possibility of corrupting the patched file.  The most common cases typically "
 1.14282 +"involve applying a patch twice, or at an incorrect location in the file.  If "
 1.14283 +"<command>patch</command> or <command role=\"hg-ext-mq\">qpush</command> ever "
 1.14284 +"mentions an offset or fuzz factor, you should make sure that the modified "
 1.14285 +"files are correct afterwards."
 1.14286 +msgstr ""
 1.14287 +
 1.14288 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14289 +#: ../en/ch12-mq.xml:678
 1.14290 +msgid ""
 1.14291 +"It's often a good idea to refresh a patch that has applied with an offset or "
 1.14292 +"fuzz factor; refreshing the patch generates new context information that will "
 1.14293 +"make it apply cleanly.  I say <quote>often,</quote> not <quote>always,</"
 1.14294 +"quote> because sometimes refreshing a patch will make it fail to apply "
 1.14295 +"against a different revision of the underlying files.  In some cases, such as "
 1.14296 +"when you're maintaining a patch that must sit on top of multiple versions of "
 1.14297 +"a source tree, it's acceptable to have a patch apply with some fuzz, provided "
 1.14298 +"you've verified the results of the patching process in such cases."
 1.14299 +msgstr ""
 1.14300 +
 1.14301 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14302 +#: ../en/ch12-mq.xml:691
 1.14303 +msgid "Handling rejection"
 1.14304 +msgstr ""
 1.14305 +
 1.14306 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14307 +#: ../en/ch12-mq.xml:693
 1.14308 +msgid ""
 1.14309 +"If <command role=\"hg-ext-mq\">qpush</command> fails to apply a patch, it "
 1.14310 +"will print an error message and exit.  If it has left <filename role=\"special"
 1.14311 +"\">.rej</filename> files behind, it is usually best to fix up the rejected "
 1.14312 +"hunks before you push more patches or do any further work."
 1.14313 +msgstr ""
 1.14314 +
 1.14315 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14316 +#: ../en/ch12-mq.xml:699
 1.14317 +msgid ""
 1.14318 +"If your patch <emphasis>used to</emphasis> apply cleanly, and no longer does "
 1.14319 +"because you've changed the underlying code that your patches are based on, "
 1.14320 +"Mercurial Queues can help; see section <xref linkend=\"sec.mq.merge\"/> for "
 1.14321 +"details."
 1.14322 +msgstr ""
 1.14323 +
 1.14324 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14325 +#: ../en/ch12-mq.xml:705
 1.14326 +msgid ""
 1.14327 +"Unfortunately, there aren't any great techniques for dealing with rejected "
 1.14328 +"hunks.  Most often, you'll need to view the <filename role=\"special\">.rej</"
 1.14329 +"filename> file and edit the target file, applying the rejected hunks by hand."
 1.14330 +msgstr ""
 1.14331 +
 1.14332 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14333 +#: ../en/ch12-mq.xml:710
 1.14334 +msgid ""
 1.14335 +"If you're feeling adventurous, Neil Brown, a Linux kernel hacker, wrote a "
 1.14336 +"tool called <command>wiggle</command> <citation>web:wiggle</citation>, which "
 1.14337 +"is more vigorous than <command>patch</command> in its attempts to make a "
 1.14338 +"patch apply."
 1.14339 +msgstr ""
 1.14340 +
 1.14341 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14342 +#: ../en/ch12-mq.xml:716
 1.14343 +msgid ""
 1.14344 +"Another Linux kernel hacker, Chris Mason (the author of Mercurial Queues), "
 1.14345 +"wrote a similar tool called <command>mpatch</command> <citation>web:mpatch</"
 1.14346 +"citation>, which takes a simple approach to automating the application of "
 1.14347 +"hunks rejected by <command>patch</command>.  The <command>mpatch</command> "
 1.14348 +"command can help with four common reasons that a hunk may be rejected:"
 1.14349 +msgstr ""
 1.14350 +
 1.14351 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14352 +#: ../en/ch12-mq.xml:725
 1.14353 +msgid "The context in the middle of a hunk has changed."
 1.14354 +msgstr ""
 1.14355 +
 1.14356 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14357 +#: ../en/ch12-mq.xml:728
 1.14358 +msgid "A hunk is missing some context at the beginning or end."
 1.14359 +msgstr ""
 1.14360 +
 1.14361 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14362 +#: ../en/ch12-mq.xml:731
 1.14363 +msgid ""
 1.14364 +"A large hunk might apply better&emdash;either entirely or in part&emdash;if "
 1.14365 +"it was broken up into smaller hunks."
 1.14366 +msgstr ""
 1.14367 +
 1.14368 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.14369 +#: ../en/ch12-mq.xml:735
 1.14370 +msgid ""
 1.14371 +"A hunk removes lines with slightly different content than those currently "
 1.14372 +"present in the file."
 1.14373 +msgstr ""
 1.14374 +
 1.14375 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14376 +#: ../en/ch12-mq.xml:739
 1.14377 +msgid ""
 1.14378 +"If you use <command>wiggle</command> or <command>mpatch</command>, you should "
 1.14379 +"be doubly careful to check your results when you're done.  In fact, "
 1.14380 +"<command>mpatch</command> enforces this method of double-checking the tool's "
 1.14381 +"output, by automatically dropping you into a merge program when it has done "
 1.14382 +"its job, so that you can verify its work and finish off any remaining merges."
 1.14383 +msgstr ""
 1.14384 +
 1.14385 +#. type: Content of: <book><chapter><sect1><title>
 1.14386 +#: ../en/ch12-mq.xml:751
 1.14387 +msgid "Getting the best performance out of MQ"
 1.14388 +msgstr ""
 1.14389 +
 1.14390 +#. type: Content of: <book><chapter><sect1><para>
 1.14391 +#: ../en/ch12-mq.xml:753
 1.14392 +msgid ""
 1.14393 +"MQ is very efficient at handling a large number of patches.  I ran some "
 1.14394 +"performance experiments in mid-2006 for a talk that I gave at the 2006 "
 1.14395 +"EuroPython conference <citation>web:europython</citation>.  I used as my data "
 1.14396 +"set the Linux 2.6.17-mm1 patch series, which consists of 1,738 patches.  I "
 1.14397 +"applied these on top of a Linux kernel repository containing all 27,472 "
 1.14398 +"revisions between Linux 2.6.12-rc2 and Linux 2.6.17."
 1.14399 +msgstr ""
 1.14400 +
 1.14401 +#. type: Content of: <book><chapter><sect1><para>
 1.14402 +#: ../en/ch12-mq.xml:762
 1.14403 +msgid ""
 1.14404 +"On my old, slow laptop, I was able to <command role=\"hg-cmd\">hg qpush "
 1.14405 +"<option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</option></command> all 1,738 "
 1.14406 +"patches in 3.5 minutes, and <command role=\"hg-cmd\">hg qpop <option role="
 1.14407 +"\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> them all in 30 seconds.  "
 1.14408 +"(On a newer laptop, the time to push all patches dropped to two minutes.)  I "
 1.14409 +"could <command role=\"hg-ext-mq\">qrefresh</command> one of the biggest "
 1.14410 +"patches (which made 22,779 lines of changes to 287 files) in 6.6 seconds."
 1.14411 +msgstr ""
 1.14412 +
 1.14413 +#. type: Content of: <book><chapter><sect1><para>
 1.14414 +#: ../en/ch12-mq.xml:773
 1.14415 +msgid ""
 1.14416 +"Clearly, MQ is well suited to working in large trees, but there are a few "
 1.14417 +"tricks you can use to get the best performance of it."
 1.14418 +msgstr ""
 1.14419 +
 1.14420 +#. type: Content of: <book><chapter><sect1><para>
 1.14421 +#: ../en/ch12-mq.xml:777
 1.14422 +msgid ""
 1.14423 +"First of all, try to <quote>batch</quote> operations together.  Every time "
 1.14424 +"you run <command role=\"hg-ext-mq\">qpush</command> or <command role=\"hg-ext-"
 1.14425 +"mq\">qpop</command>, these commands scan the working directory once to make "
 1.14426 +"sure you haven't made some changes and then forgotten to run <command role="
 1.14427 +"\"hg-ext-mq\">qrefresh</command>.  On a small tree, the time that this scan "
 1.14428 +"takes is unnoticeable.  However, on a medium-sized tree (containing tens of "
 1.14429 +"thousands of files), it can take a second or more."
 1.14430 +msgstr ""
 1.14431 +
 1.14432 +#. type: Content of: <book><chapter><sect1><para>
 1.14433 +#: ../en/ch12-mq.xml:788
 1.14434 +msgid ""
 1.14435 +"The <command role=\"hg-ext-mq\">qpush</command> and <command role=\"hg-ext-mq"
 1.14436 +"\">qpop</command> commands allow you to push and pop multiple patches at a "
 1.14437 +"time.  You can identify the <quote>destination patch</quote> that you want to "
 1.14438 +"end up at.  When you <command role=\"hg-ext-mq\">qpush</command> with a "
 1.14439 +"destination specified, it will push patches until that patch is at the top of "
 1.14440 +"the applied stack.  When you <command role=\"hg-ext-mq\">qpop</command> to a "
 1.14441 +"destination, MQ will pop patches until the destination patch is at the top."
 1.14442 +msgstr ""
 1.14443 +
 1.14444 +#. type: Content of: <book><chapter><sect1><para>
 1.14445 +#: ../en/ch12-mq.xml:798
 1.14446 +msgid ""
 1.14447 +"You can identify a destination patch using either the name of the patch, or "
 1.14448 +"by number.  If you use numeric addressing, patches are counted from zero; "
 1.14449 +"this means that the first patch is zero, the second is one, and so on."
 1.14450 +msgstr ""
 1.14451 +
 1.14452 +#. type: Content of: <book><chapter><sect1><title>
 1.14453 +#: ../en/ch12-mq.xml:805
 1.14454 +msgid "Updating your patches when the underlying code changes"
 1.14455 +msgstr ""
 1.14456 +
 1.14457 +#. type: Content of: <book><chapter><sect1><para>
 1.14458 +#: ../en/ch12-mq.xml:808
 1.14459 +msgid ""
 1.14460 +"It's common to have a stack of patches on top of an underlying repository "
 1.14461 +"that you don't modify directly.  If you're working on changes to third-party "
 1.14462 +"code, or on a feature that is taking longer to develop than the rate of "
 1.14463 +"change of the code beneath, you will often need to sync up with the "
 1.14464 +"underlying code, and fix up any hunks in your patches that no longer apply.  "
 1.14465 +"This is called <emphasis>rebasing</emphasis> your patch series."
 1.14466 +msgstr ""
 1.14467 +
 1.14468 +#. type: Content of: <book><chapter><sect1><para>
 1.14469 +#: ../en/ch12-mq.xml:817
 1.14470 +msgid ""
 1.14471 +"The simplest way to do this is to <command role=\"hg-cmd\">hg qpop <option "
 1.14472 +"role=\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> your patches, then "
 1.14473 +"<command role=\"hg-cmd\">hg pull</command> changes into the underlying "
 1.14474 +"repository, and finally <command role=\"hg-cmd\">hg qpush <option role=\"hg-"
 1.14475 +"ext-mq-cmd-qpop-opt\">hg -a</option></command> your patches again.  MQ will "
 1.14476 +"stop pushing any time it runs across a patch that fails to apply during "
 1.14477 +"conflicts, allowing you to fix your conflicts, <command role=\"hg-ext-mq"
 1.14478 +"\">qrefresh</command> the affected patch, and continue pushing until you have "
 1.14479 +"fixed your entire stack."
 1.14480 +msgstr ""
 1.14481 +
 1.14482 +#. type: Content of: <book><chapter><sect1><para>
 1.14483 +#: ../en/ch12-mq.xml:829
 1.14484 +msgid ""
 1.14485 +"This approach is easy to use and works well if you don't expect changes to "
 1.14486 +"the underlying code to affect how well your patches apply. If your patch "
 1.14487 +"stack touches code that is modified frequently or invasively in the "
 1.14488 +"underlying repository, however, fixing up rejected hunks by hand quickly "
 1.14489 +"becomes tiresome."
 1.14490 +msgstr ""
 1.14491 +
 1.14492 +#. type: Content of: <book><chapter><sect1><para>
 1.14493 +#: ../en/ch12-mq.xml:836
 1.14494 +msgid ""
 1.14495 +"It's possible to partially automate the rebasing process.  If your patches "
 1.14496 +"apply cleanly against some revision of the underlying repo, MQ can use this "
 1.14497 +"information to help you to resolve conflicts between your patches and a "
 1.14498 +"different revision."
 1.14499 +msgstr ""
 1.14500 +
 1.14501 +#. type: Content of: <book><chapter><sect1><para>
 1.14502 +#: ../en/ch12-mq.xml:842
 1.14503 +msgid "The process is a little involved."
 1.14504 +msgstr ""
 1.14505 +
 1.14506 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.14507 +#: ../en/ch12-mq.xml:844
 1.14508 +msgid ""
 1.14509 +"To begin, <command role=\"hg-cmd\">hg qpush -a</command> all of your patches "
 1.14510 +"on top of the revision where you know that they apply cleanly."
 1.14511 +msgstr ""
 1.14512 +
 1.14513 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.14514 +#: ../en/ch12-mq.xml:848
 1.14515 +msgid ""
 1.14516 +"Save a backup copy of your patch directory using <command role=\"hg-cmd\">hg "
 1.14517 +"qsave <option role=\"hg-ext-mq-cmd-qsave-opt\">hg -e</option> <option role="
 1.14518 +"\"hg-ext-mq-cmd-qsave-opt\">hg -c</option></command>.  This prints the name "
 1.14519 +"of the directory that it has saved the patches in.  It will save the patches "
 1.14520 +"to a directory called <filename role=\"special\" class=\"directory\">.hg/"
 1.14521 +"patches.N</filename>, where <literal>N</literal> is a small integer.  It also "
 1.14522 +"commits a <quote>save changeset</quote> on top of your applied patches; this "
 1.14523 +"is for internal book-keeping, and records the states of the <filename role="
 1.14524 +"\"special\">series</filename> and <filename role=\"special\">status</"
 1.14525 +"filename> files."
 1.14526 +msgstr ""
 1.14527 +
 1.14528 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.14529 +#: ../en/ch12-mq.xml:862
 1.14530 +msgid ""
 1.14531 +"Use <command role=\"hg-cmd\">hg pull</command> to bring new changes into the "
 1.14532 +"underlying repository.  (Don't run <command role=\"hg-cmd\">hg pull -u</"
 1.14533 +"command>; see below for why.)"
 1.14534 +msgstr ""
 1.14535 +
 1.14536 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.14537 +#: ../en/ch12-mq.xml:867
 1.14538 +msgid ""
 1.14539 +"Update to the new tip revision, using <command role=\"hg-cmd\">hg update "
 1.14540 +"<option role=\"hg-opt-update\">-C</option></command> to override the patches "
 1.14541 +"you have pushed."
 1.14542 +msgstr ""
 1.14543 +
 1.14544 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.14545 +#: ../en/ch12-mq.xml:872
 1.14546 +msgid ""
 1.14547 +"Merge all patches using \\hgcmdargs{qpush}{<option role=\"hg-ext-mq-cmd-qpush-"
 1.14548 +"opt\">hg -m</option> <option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</"
 1.14549 +"option>}.  The <option role=\"hg-ext-mq-cmd-qpush-opt\">hg -m</option> option "
 1.14550 +"to <command role=\"hg-ext-mq\">qpush</command> tells MQ to perform a three-"
 1.14551 +"way merge if the patch fails to apply."
 1.14552 +msgstr ""
 1.14553 +
 1.14554 +#. type: Content of: <book><chapter><sect1><para>
 1.14555 +#: ../en/ch12-mq.xml:882
 1.14556 +msgid ""
 1.14557 +"During the <command role=\"hg-cmd\">hg qpush <option role=\"hg-ext-mq-cmd-"
 1.14558 +"qpush-opt\">hg -m</option></command>, each patch in the <filename role="
 1.14559 +"\"special\">series</filename> file is applied normally.  If a patch applies "
 1.14560 +"with fuzz or rejects, MQ looks at the queue you <command role=\"hg-ext-mq"
 1.14561 +"\">qsave</command>d, and performs a three-way merge with the corresponding "
 1.14562 +"changeset.  This merge uses Mercurial's normal merge machinery, so it may pop "
 1.14563 +"up a GUI merge tool to help you to resolve problems."
 1.14564 +msgstr ""
 1.14565 +
 1.14566 +#. type: Content of: <book><chapter><sect1><para>
 1.14567 +#: ../en/ch12-mq.xml:892
 1.14568 +msgid ""
 1.14569 +"When you finish resolving the effects of a patch, MQ refreshes your patch "
 1.14570 +"based on the result of the merge."
 1.14571 +msgstr ""
 1.14572 +
 1.14573 +#. type: Content of: <book><chapter><sect1><para>
 1.14574 +#: ../en/ch12-mq.xml:895
 1.14575 +msgid ""
 1.14576 +"At the end of this process, your repository will have one extra head from the "
 1.14577 +"old patch queue, and a copy of the old patch queue will be in <filename role="
 1.14578 +"\"special\" class=\"directory\">.hg/patches.N</filename>. You can remove the "
 1.14579 +"extra head using <command role=\"hg-cmd\">hg qpop -a -n patches.N</command> "
 1.14580 +"or <command role=\"hg-cmd\">hg strip</command>.  You can delete <filename "
 1.14581 +"role=\"special\" class=\"directory\">.hg/patches.N</filename> once you are "
 1.14582 +"sure that you no longer need it as a backup."
 1.14583 +msgstr ""
 1.14584 +
 1.14585 +#. type: Content of: <book><chapter><sect1><title>
 1.14586 +#: ../en/ch12-mq.xml:907
 1.14587 +msgid "Identifying patches"
 1.14588 +msgstr ""
 1.14589 +
 1.14590 +#. type: Content of: <book><chapter><sect1><para>
 1.14591 +#: ../en/ch12-mq.xml:909
 1.14592 +msgid ""
 1.14593 +"MQ commands that work with patches let you refer to a patch either by using "
 1.14594 +"its name or by a number.  By name is obvious enough; pass the name "
 1.14595 +"<filename>foo.patch</filename> to <command role=\"hg-ext-mq\">qpush</"
 1.14596 +"command>, for example, and it will push patches until <filename>foo.patch</"
 1.14597 +"filename> is applied."
 1.14598 +msgstr ""
 1.14599 +
 1.14600 +#. type: Content of: <book><chapter><sect1><para>
 1.14601 +#: ../en/ch12-mq.xml:916
 1.14602 +msgid ""
 1.14603 +"As a shortcut, you can refer to a patch using both a name and a numeric "
 1.14604 +"offset; <literal>foo.patch-2</literal> means <quote>two patches before "
 1.14605 +"<literal>foo.patch</literal></quote>, while <literal>bar.patch+4</literal> "
 1.14606 +"means <quote>four patches after <literal>bar.patch</literal></quote>."
 1.14607 +msgstr ""
 1.14608 +
 1.14609 +#. type: Content of: <book><chapter><sect1><para>
 1.14610 +#: ../en/ch12-mq.xml:922
 1.14611 +msgid ""
 1.14612 +"Referring to a patch by index isn't much different.  The first patch printed "
 1.14613 +"in the output of <command role=\"hg-ext-mq\">qseries</command> is patch zero "
 1.14614 +"(yes, it's one of those start-at-zero counting systems); the second is patch "
 1.14615 +"one; and so on."
 1.14616 +msgstr ""
 1.14617 +
 1.14618 +#. type: Content of: <book><chapter><sect1><para>
 1.14619 +#: ../en/ch12-mq.xml:928
 1.14620 +msgid ""
 1.14621 +"MQ also makes it easy to work with patches when you are using normal "
 1.14622 +"Mercurial commands.  Every command that accepts a changeset ID will also "
 1.14623 +"accept the name of an applied patch.  MQ augments the tags normally in the "
 1.14624 +"repository with an eponymous one for each applied patch.  In addition, the "
 1.14625 +"special tags \\index{tags!special tag names!<literal>qbase</literal>}"
 1.14626 +"<literal>qbase</literal> and \\index{tags!special tag names!<literal>qtip</"
 1.14627 +"literal>}<literal>qtip</literal> identify the <quote>bottom-most</quote> and "
 1.14628 +"topmost applied patches, respectively."
 1.14629 +msgstr ""
 1.14630 +
 1.14631 +#. type: Content of: <book><chapter><sect1><para>
 1.14632 +#: ../en/ch12-mq.xml:940
 1.14633 +msgid ""
 1.14634 +"These additions to Mercurial's normal tagging capabilities make dealing with "
 1.14635 +"patches even more of a breeze."
 1.14636 +msgstr ""
 1.14637 +
 1.14638 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.14639 +#: ../en/ch12-mq.xml:943
 1.14640 +msgid "Want to patchbomb a mailing list with your latest series of changes?"
 1.14641 +msgstr ""
 1.14642 +
 1.14643 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.14644 +#: ../en/ch12-mq.xml:947
 1.14645 +msgid ""
 1.14646 +"(Don't know what <quote>patchbombing</quote> is? See section <xref linkend="
 1.14647 +"\"sec.hgext.patchbomb\"/>.)"
 1.14648 +msgstr ""
 1.14649 +
 1.14650 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.14651 +#: ../en/ch12-mq.xml:950
 1.14652 +msgid ""
 1.14653 +"Need to see all of the patches since <literal>foo.patch</literal> that have "
 1.14654 +"touched files in a subdirectory of your tree?"
 1.14655 +msgstr ""
 1.14656 +
 1.14657 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><programlisting><emphasis>
 1.14658 +#: ../en/ch12-mq.xml:954
 1.14659 +msgid "subdir"
 1.14660 +msgstr ""
 1.14661 +
 1.14662 +#. type: Content of: <book><chapter><sect1><para>
 1.14663 +#: ../en/ch12-mq.xml:959
 1.14664 +msgid ""
 1.14665 +"Because MQ makes the names of patches available to the rest of Mercurial "
 1.14666 +"through its normal internal tag machinery, you don't need to type in the "
 1.14667 +"entire name of a patch when you want to identify it by name."
 1.14668 +msgstr ""
 1.14669 +
 1.14670 +#. type: Content of: <book><chapter><sect1><para>
 1.14671 +#: ../en/ch12-mq.xml:964
 1.14672 +msgid ""
 1.14673 +"Another nice consequence of representing patch names as tags is that when you "
 1.14674 +"run the <command role=\"hg-cmd\">hg log</command> command, it will display a "
 1.14675 +"patch's name as a tag, simply as part of its normal output.  This makes it "
 1.14676 +"easy to visually distinguish applied patches from underlying <quote>normal</"
 1.14677 +"quote> revisions.  The following example shows a few normal Mercurial "
 1.14678 +"commands in use with applied patches."
 1.14679 +msgstr ""
 1.14680 +
 1.14681 +#. type: Content of: <book><chapter><sect1><title>
 1.14682 +#: ../en/ch12-mq.xml:977
 1.14683 +msgid "Useful things to know about"
 1.14684 +msgstr ""
 1.14685 +
 1.14686 +#. type: Content of: <book><chapter><sect1><para>
 1.14687 +#: ../en/ch12-mq.xml:979
 1.14688 +msgid ""
 1.14689 +"There are a number of aspects of MQ usage that don't fit tidily into sections "
 1.14690 +"of their own, but that are good to know.  Here they are, in one place."
 1.14691 +msgstr ""
 1.14692 +
 1.14693 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.14694 +#: ../en/ch12-mq.xml:984
 1.14695 +msgid ""
 1.14696 +"Normally, when you <command role=\"hg-ext-mq\">qpop</command> a patch and "
 1.14697 +"<command role=\"hg-ext-mq\">qpush</command> it again, the changeset that "
 1.14698 +"represents the patch after the pop/push will have a <emphasis>different "
 1.14699 +"identity</emphasis> than the changeset that represented the hash beforehand.  "
 1.14700 +"See section <xref linkend=\"sec.mqref.cmd.qpush\"/> for information as to why "
 1.14701 +"this is."
 1.14702 +msgstr ""
 1.14703 +
 1.14704 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.14705 +#: ../en/ch12-mq.xml:993
 1.14706 +msgid ""
 1.14707 +"It's not a good idea to <command role=\"hg-cmd\">hg merge</command> changes "
 1.14708 +"from another branch with a patch changeset, at least if you want to maintain "
 1.14709 +"the <quote>patchiness</quote> of that changeset and changesets below it on "
 1.14710 +"the patch stack.  If you try to do this, it will appear to succeed, but MQ "
 1.14711 +"will become confused."
 1.14712 +msgstr ""
 1.14713 +
 1.14714 +#. type: Content of: <book><chapter><sect1><title>
 1.14715 +#: ../en/ch12-mq.xml:1004
 1.14716 +msgid "Managing patches in a repository"
 1.14717 +msgstr ""
 1.14718 +
 1.14719 +#. type: Content of: <book><chapter><sect1><para>
 1.14720 +#: ../en/ch12-mq.xml:1006
 1.14721 +msgid ""
 1.14722 +"Because MQ's <filename role=\"special\" class=\"directory\">.hg/patches</"
 1.14723 +"filename> directory resides outside a Mercurial repository's working "
 1.14724 +"directory, the <quote>underlying</quote> Mercurial repository knows nothing "
 1.14725 +"about the management or presence of patches."
 1.14726 +msgstr ""
 1.14727 +
 1.14728 +#. type: Content of: <book><chapter><sect1><para>
 1.14729 +#: ../en/ch12-mq.xml:1012
 1.14730 +msgid ""
 1.14731 +"This presents the interesting possibility of managing the contents of the "
 1.14732 +"patch directory as a Mercurial repository in its own right.  This can be a "
 1.14733 +"useful way to work.  For example, you can work on a patch for a while, "
 1.14734 +"<command role=\"hg-ext-mq\">qrefresh</command> it, then <command role=\"hg-cmd"
 1.14735 +"\">hg commit</command> the current state of the patch.  This lets you "
 1.14736 +"<quote>roll back</quote> to that version of the patch later on."
 1.14737 +msgstr ""
 1.14738 +
 1.14739 +#. type: Content of: <book><chapter><sect1><para>
 1.14740 +#: ../en/ch12-mq.xml:1021
 1.14741 +msgid ""
 1.14742 +"You can then share different versions of the same patch stack among multiple "
 1.14743 +"underlying repositories.  I use this when I am developing a Linux kernel "
 1.14744 +"feature.  I have a pristine copy of my kernel sources for each of several CPU "
 1.14745 +"architectures, and a cloned repository under each that contains the patches I "
 1.14746 +"am working on.  When I want to test a change on a different architecture, I "
 1.14747 +"push my current patches to the patch repository associated with that kernel "
 1.14748 +"tree, pop and push all of my patches, and build and test that kernel."
 1.14749 +msgstr ""
 1.14750 +
 1.14751 +#. type: Content of: <book><chapter><sect1><para>
 1.14752 +#: ../en/ch12-mq.xml:1031
 1.14753 +msgid ""
 1.14754 +"Managing patches in a repository makes it possible for multiple developers to "
 1.14755 +"work on the same patch series without colliding with each other, all on top "
 1.14756 +"of an underlying source base that they may or may not control."
 1.14757 +msgstr ""
 1.14758 +
 1.14759 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14760 +#: ../en/ch12-mq.xml:1037
 1.14761 +msgid "MQ support for patch repositories"
 1.14762 +msgstr ""
 1.14763 +
 1.14764 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14765 +#: ../en/ch12-mq.xml:1039
 1.14766 +msgid ""
 1.14767 +"MQ helps you to work with the <filename role=\"special\" class=\"directory\">."
 1.14768 +"hg/patches</filename> directory as a repository; when you prepare a "
 1.14769 +"repository for working with patches using <command role=\"hg-ext-mq\">qinit</"
 1.14770 +"command>, you can pass the <option role=\"hg-ext-mq-cmd-qinit-opt\">hg -c</"
 1.14771 +"option> option to create the <filename role=\"special\" class=\"directory\">."
 1.14772 +"hg/patches</filename> directory as a Mercurial repository."
 1.14773 +msgstr ""
 1.14774 +
 1.14775 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
 1.14776 +#: ../en/ch12-mq.xml:1049
 1.14777 +msgid ""
 1.14778 +"If you forget to use the <option role=\"hg-ext-mq-cmd-qinit-opt\">hg -c</"
 1.14779 +"option> option, you can simply go into the <filename role=\"special\" class="
 1.14780 +"\"directory\">.hg/patches</filename> directory at any time and run <command "
 1.14781 +"role=\"hg-cmd\">hg init</command>.  Don't forget to add an entry for the "
 1.14782 +"<filename role=\"special\">status</filename> file to the <filename role="
 1.14783 +"\"special\">.hgignore</filename> file, though"
 1.14784 +msgstr ""
 1.14785 +
 1.14786 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
 1.14787 +#: ../en/ch12-mq.xml:1058
 1.14788 +msgid ""
 1.14789 +"(<command role=\"hg-cmd\">hg qinit <option role=\"hg-ext-mq-cmd-qinit-opt"
 1.14790 +"\">hg -c</option></command> does this for you automatically); you "
 1.14791 +"<emphasis>really</emphasis> don't want to manage the <filename role=\"special"
 1.14792 +"\">status</filename> file."
 1.14793 +msgstr ""
 1.14794 +
 1.14795 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14796 +#: ../en/ch12-mq.xml:1065
 1.14797 +msgid ""
 1.14798 +"As a convenience, if MQ notices that the <filename class=\"directory\">.hg/"
 1.14799 +"patches</filename> directory is a repository, it will automatically <command "
 1.14800 +"role=\"hg-cmd\">hg add</command> every patch that you create and import."
 1.14801 +msgstr ""
 1.14802 +
 1.14803 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14804 +#: ../en/ch12-mq.xml:1070
 1.14805 +msgid ""
 1.14806 +"MQ provides a shortcut command, <command role=\"hg-ext-mq\">qcommit</"
 1.14807 +"command>, that runs <command role=\"hg-cmd\">hg commit</command> in the "
 1.14808 +"<filename role=\"special\" class=\"directory\">.hg/patches</filename> "
 1.14809 +"directory.  This saves some bothersome typing."
 1.14810 +msgstr ""
 1.14811 +
 1.14812 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14813 +#: ../en/ch12-mq.xml:1076
 1.14814 +msgid ""
 1.14815 +"Finally, as a convenience to manage the patch directory, you can define the "
 1.14816 +"alias <command>mq</command> on Unix systems. For example, on Linux systems "
 1.14817 +"using the <command>bash</command> shell, you can include the following "
 1.14818 +"snippet in your <filename role=\"home\">~/.bashrc</filename>."
 1.14819 +msgstr ""
 1.14820 +
 1.14821 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14822 +#: ../en/ch12-mq.xml:1086
 1.14823 +msgid ""
 1.14824 +"You can then issue commands of the form <command>mq pull</command> from the "
 1.14825 +"main repository."
 1.14826 +msgstr ""
 1.14827 +
 1.14828 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14829 +#: ../en/ch12-mq.xml:1091
 1.14830 +msgid "A few things to watch out for"
 1.14831 +msgstr ""
 1.14832 +
 1.14833 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14834 +#: ../en/ch12-mq.xml:1093
 1.14835 +msgid ""
 1.14836 +"MQ's support for working with a repository full of patches is limited in a "
 1.14837 +"few small respects."
 1.14838 +msgstr ""
 1.14839 +
 1.14840 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14841 +#: ../en/ch12-mq.xml:1096
 1.14842 +msgid ""
 1.14843 +"MQ cannot automatically detect changes that you make to the patch directory.  "
 1.14844 +"If you <command role=\"hg-cmd\">hg pull</command>, manually edit, or <command "
 1.14845 +"role=\"hg-cmd\">hg update</command> changes to patches or the <filename role="
 1.14846 +"\"special\">series</filename> file, you will have to <command role=\"hg-cmd"
 1.14847 +"\">hg qpop <option role=\"hg-ext-mq-cmd-qpop-opt\">hg -a</option></command> "
 1.14848 +"and then <command role=\"hg-cmd\">hg qpush <option role=\"hg-ext-mq-cmd-qpush-"
 1.14849 +"opt\">hg -a</option></command> in the underlying repository to see those "
 1.14850 +"changes show up there.  If you forget to do this, you can confuse MQ's idea "
 1.14851 +"of which patches are applied."
 1.14852 +msgstr ""
 1.14853 +
 1.14854 +#. type: Content of: <book><chapter><sect1><title>
 1.14855 +#: ../en/ch12-mq.xml:1112
 1.14856 +msgid "Third party tools for working with patches"
 1.14857 +msgstr ""
 1.14858 +
 1.14859 +#. type: Content of: <book><chapter><sect1><para>
 1.14860 +#: ../en/ch12-mq.xml:1114
 1.14861 +msgid ""
 1.14862 +"Once you've been working with patches for a while, you'll find yourself "
 1.14863 +"hungry for tools that will help you to understand and manipulate the patches "
 1.14864 +"you're dealing with."
 1.14865 +msgstr ""
 1.14866 +
 1.14867 +#. type: Content of: <book><chapter><sect1><para>
 1.14868 +#: ../en/ch12-mq.xml:1118
 1.14869 +msgid ""
 1.14870 +"The <command>diffstat</command> command <citation>web:diffstat</citation> "
 1.14871 +"generates a histogram of the modifications made to each file in a patch.  It "
 1.14872 +"provides a good way to <quote>get a sense of</quote> a patch&emdash;which "
 1.14873 +"files it affects, and how much change it introduces to each file and as a "
 1.14874 +"whole.  (I find that it's a good idea to use <command>diffstat</command>'s "
 1.14875 +"<option role=\"cmd-opt-diffstat\">-p</option> option as a matter of course, "
 1.14876 +"as otherwise it will try to do clever things with prefixes of file names that "
 1.14877 +"inevitably confuse at least me.)"
 1.14878 +msgstr ""
 1.14879 +
 1.14880 +#. type: Content of: <book><chapter><sect1><para>
 1.14881 +#: ../en/ch12-mq.xml:1132
 1.14882 +msgid ""
 1.14883 +"The <literal role=\"package\">patchutils</literal> package <citation>web:"
 1.14884 +"patchutils</citation> is invaluable. It provides a set of small utilities "
 1.14885 +"that follow the <quote>Unix philosophy;</quote> each does one useful thing "
 1.14886 +"with a patch.  The <literal role=\"package\">patchutils</literal> command I "
 1.14887 +"use most is <command>filterdiff</command>, which extracts subsets from a "
 1.14888 +"patch file.  For example, given a patch that modifies hundreds of files "
 1.14889 +"across dozens of directories, a single invocation of <command>filterdiff</"
 1.14890 +"command> can generate a smaller patch that only touches files whose names "
 1.14891 +"match a particular glob pattern.  See section <xref linkend=\"mq-collab.tips."
 1.14892 +"interdiff\"/> for another example."
 1.14893 +msgstr ""
 1.14894 +
 1.14895 +#. type: Content of: <book><chapter><sect1><title>
 1.14896 +#: ../en/ch12-mq.xml:1148
 1.14897 +msgid "Good ways to work with patches"
 1.14898 +msgstr ""
 1.14899 +
 1.14900 +#. type: Content of: <book><chapter><sect1><para>
 1.14901 +#: ../en/ch12-mq.xml:1150
 1.14902 +msgid ""
 1.14903 +"Whether you are working on a patch series to submit to a free software or "
 1.14904 +"open source project, or a series that you intend to treat as a sequence of "
 1.14905 +"regular changesets when you're done, you can use some simple techniques to "
 1.14906 +"keep your work well organised."
 1.14907 +msgstr ""
 1.14908 +
 1.14909 +#. type: Content of: <book><chapter><sect1><para>
 1.14910 +#: ../en/ch12-mq.xml:1156
 1.14911 +msgid ""
 1.14912 +"Give your patches descriptive names.  A good name for a patch might be "
 1.14913 +"<filename>rework-device-alloc.patch</filename>, because it will immediately "
 1.14914 +"give you a hint what the purpose of the patch is.  Long names shouldn't be a "
 1.14915 +"problem; you won't be typing the names often, but you <emphasis>will</"
 1.14916 +"emphasis> be running commands like <command role=\"hg-ext-mq\">qapplied</"
 1.14917 +"command> and <command role=\"hg-ext-mq\">qtop</command> over and over. Good "
 1.14918 +"naming becomes especially important when you have a number of patches to work "
 1.14919 +"with, or if you are juggling a number of different tasks and your patches "
 1.14920 +"only get a fraction of your attention."
 1.14921 +msgstr ""
 1.14922 +
 1.14923 +#. type: Content of: <book><chapter><sect1><para>
 1.14924 +#: ../en/ch12-mq.xml:1168
 1.14925 +msgid ""
 1.14926 +"Be aware of what patch you're working on.  Use the <command role=\"hg-ext-mq"
 1.14927 +"\">qtop</command> command and skim over the text of your patches "
 1.14928 +"frequently&emdash;for example, using <command role=\"hg-cmd\">hg tip <option "
 1.14929 +"role=\"hg-opt-tip\">-p</option></command>)&emdash;to be sure of where you "
 1.14930 +"stand.  I have several times worked on and <command role=\"hg-ext-mq"
 1.14931 +"\">qrefresh</command>ed a patch other than the one I intended, and it's often "
 1.14932 +"tricky to migrate changes into the right patch after making them in the wrong "
 1.14933 +"one."
 1.14934 +msgstr ""
 1.14935 +
 1.14936 +#. type: Content of: <book><chapter><sect1><para>
 1.14937 +#: ../en/ch12-mq.xml:1178
 1.14938 +msgid ""
 1.14939 +"For this reason, it is very much worth investing a little time to learn how "
 1.14940 +"to use some of the third-party tools I described in section <xref linkend="
 1.14941 +"\"sec.mq.tools\"/>, particularly <command>diffstat</command> and "
 1.14942 +"<command>filterdiff</command>.  The former will give you a quick idea of what "
 1.14943 +"changes your patch is making, while the latter makes it easy to splice hunks "
 1.14944 +"selectively out of one patch and into another."
 1.14945 +msgstr ""
 1.14946 +
 1.14947 +#. type: Content of: <book><chapter><sect1><title>
 1.14948 +#: ../en/ch12-mq.xml:1189
 1.14949 +msgid "MQ cookbook"
 1.14950 +msgstr ""
 1.14951 +
 1.14952 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.14953 +#: ../en/ch12-mq.xml:1192
 1.14954 +msgid "Manage <quote>trivial</quote> patches"
 1.14955 +msgstr ""
 1.14956 +
 1.14957 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14958 +#: ../en/ch12-mq.xml:1194
 1.14959 +msgid ""
 1.14960 +"Because the overhead of dropping files into a new Mercurial repository is so "
 1.14961 +"low, it makes a lot of sense to manage patches this way even if you simply "
 1.14962 +"want to make a few changes to a source tarball that you downloaded."
 1.14963 +msgstr ""
 1.14964 +
 1.14965 +#
 1.14966 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14967 +#: ../en/ch12-mq.xml:1199
 1.14968 +msgid ""
 1.14969 +"Begin by downloading and unpacking the source tarball, and turning it into a "
 1.14970 +"Mercurial repository."
 1.14971 +msgstr ""
 1.14972 +
 1.14973 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14974 +#: ../en/ch12-mq.xml:1204
 1.14975 +msgid "Continue by creating a patch stack and making your changes."
 1.14976 +msgstr ""
 1.14977 +
 1.14978 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14979 +#: ../en/ch12-mq.xml:1209
 1.14980 +msgid ""
 1.14981 +"Let's say a few weeks or months pass, and your package author releases a new "
 1.14982 +"version.  First, bring their changes into the repository."
 1.14983 +msgstr ""
 1.14984 +
 1.14985 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14986 +#: ../en/ch12-mq.xml:1215
 1.14987 +msgid ""
 1.14988 +"The pipeline starting with <command role=\"hg-cmd\">hg locate</command> above "
 1.14989 +"deletes all files in the working directory, so that <command role=\"hg-cmd"
 1.14990 +"\">hg commit</command>'s <option role=\"hg-opt-commit\">--addremove</option> "
 1.14991 +"option can actually tell which files have really been removed in the newer "
 1.14992 +"version of the source."
 1.14993 +msgstr ""
 1.14994 +
 1.14995 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.14996 +#: ../en/ch12-mq.xml:1223
 1.14997 +msgid "Finally, you can apply your patches on top of the new tree."
 1.14998 +msgstr ""
 1.14999 +
 1.15000 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.15001 +#: ../en/ch12-mq.xml:1230
 1.15002 +msgid "Combining entire patches"
 1.15003 +msgstr ""
 1.15004 +
 1.15005 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15006 +#: ../en/ch12-mq.xml:1232
 1.15007 +msgid ""
 1.15008 +"MQ provides a command, <command role=\"hg-ext-mq\">qfold</command> that lets "
 1.15009 +"you combine entire patches.  This <quote>folds</quote> the patches you name, "
 1.15010 +"in the order you name them, into the topmost applied patch, and concatenates "
 1.15011 +"their descriptions onto the end of its description.  The patches that you "
 1.15012 +"fold must be unapplied before you fold them."
 1.15013 +msgstr ""
 1.15014 +
 1.15015 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15016 +#: ../en/ch12-mq.xml:1240
 1.15017 +msgid ""
 1.15018 +"The order in which you fold patches matters.  If your topmost applied patch "
 1.15019 +"is <literal>foo</literal>, and you <command role=\"hg-ext-mq\">qfold</"
 1.15020 +"command> <literal>bar</literal> and <literal>quux</literal> into it, you will "
 1.15021 +"end up with a patch that has the same effect as if you applied first "
 1.15022 +"<literal>foo</literal>, then <literal>bar</literal>, followed by "
 1.15023 +"<literal>quux</literal>."
 1.15024 +msgstr ""
 1.15025 +
 1.15026 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.15027 +#: ../en/ch12-mq.xml:1251
 1.15028 +msgid "Merging part of one patch into another"
 1.15029 +msgstr ""
 1.15030 +
 1.15031 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15032 +#: ../en/ch12-mq.xml:1253
 1.15033 +msgid ""
 1.15034 +"Merging <emphasis>part</emphasis> of one patch into another is more difficult "
 1.15035 +"than combining entire patches."
 1.15036 +msgstr ""
 1.15037 +
 1.15038 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15039 +#: ../en/ch12-mq.xml:1257
 1.15040 +msgid ""
 1.15041 +"If you want to move changes to entire files, you can use <command>filterdiff</"
 1.15042 +"command>'s <option role=\"cmd-opt-filterdiff\">-i</option> and <option role="
 1.15043 +"\"cmd-opt-filterdiff\">-x</option> options to choose the modifications to "
 1.15044 +"snip out of one patch, concatenating its output onto the end of the patch you "
 1.15045 +"want to merge into.  You usually won't need to modify the patch you've merged "
 1.15046 +"the changes from.  Instead, MQ will report some rejected hunks when you "
 1.15047 +"<command role=\"hg-ext-mq\">qpush</command> it (from the hunks you moved into "
 1.15048 +"the other patch), and you can simply <command role=\"hg-ext-mq\">qrefresh</"
 1.15049 +"command> the patch to drop the duplicate hunks."
 1.15050 +msgstr ""
 1.15051 +
 1.15052 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15053 +#: ../en/ch12-mq.xml:1270
 1.15054 +msgid ""
 1.15055 +"If you have a patch that has multiple hunks modifying a file, and you only "
 1.15056 +"want to move a few of those hunks, the job becomes more messy, but you can "
 1.15057 +"still partly automate it.  Use <command>lsdiff -nvv</command> to print some "
 1.15058 +"metadata about the patch."
 1.15059 +msgstr ""
 1.15060 +
 1.15061 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15062 +#: ../en/ch12-mq.xml:1278
 1.15063 +msgid "This command prints three different kinds of number:"
 1.15064 +msgstr ""
 1.15065 +
 1.15066 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.15067 +#: ../en/ch12-mq.xml:1281
 1.15068 +msgid ""
 1.15069 +"(in the first column) a <emphasis>file number</emphasis> to identify each "
 1.15070 +"file modified in the patch;"
 1.15071 +msgstr ""
 1.15072 +
 1.15073 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.15074 +#: ../en/ch12-mq.xml:1285
 1.15075 +msgid ""
 1.15076 +"(on the next line, indented) the line number within a modified file where a "
 1.15077 +"hunk starts; and"
 1.15078 +msgstr ""
 1.15079 +
 1.15080 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.15081 +#: ../en/ch12-mq.xml:1288
 1.15082 +msgid ""
 1.15083 +"(on the same line) a <emphasis>hunk number</emphasis> to identify that hunk."
 1.15084 +msgstr ""
 1.15085 +
 1.15086 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15087 +#: ../en/ch12-mq.xml:1292
 1.15088 +msgid ""
 1.15089 +"You'll have to use some visual inspection, and reading of the patch, to "
 1.15090 +"identify the file and hunk numbers you'll want, but you can then pass them to "
 1.15091 +"to <command>filterdiff</command>'s <option role=\"cmd-opt-filterdiff\">--"
 1.15092 +"files</option> and <option role=\"cmd-opt-filterdiff\">--hunks</option> "
 1.15093 +"options, to select exactly the file and hunk you want to extract."
 1.15094 +msgstr ""
 1.15095 +
 1.15096 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15097 +#: ../en/ch12-mq.xml:1300
 1.15098 +msgid ""
 1.15099 +"Once you have this hunk, you can concatenate it onto the end of your "
 1.15100 +"destination patch and continue with the remainder of section <xref linkend="
 1.15101 +"\"sec.mq.combine\"/>."
 1.15102 +msgstr ""
 1.15103 +
 1.15104 +#. type: Content of: <book><chapter><sect1><title>
 1.15105 +#: ../en/ch12-mq.xml:1307
 1.15106 +msgid "Differences between quilt and MQ"
 1.15107 +msgstr ""
 1.15108 +
 1.15109 +#. type: Content of: <book><chapter><sect1><para>
 1.15110 +#: ../en/ch12-mq.xml:1309
 1.15111 +msgid ""
 1.15112 +"If you are already familiar with quilt, MQ provides a similar command set.  "
 1.15113 +"There are a few differences in the way that it works."
 1.15114 +msgstr ""
 1.15115 +
 1.15116 +#. type: Content of: <book><chapter><sect1><para>
 1.15117 +#: ../en/ch12-mq.xml:1313
 1.15118 +msgid ""
 1.15119 +"You will already have noticed that most quilt commands have MQ counterparts "
 1.15120 +"that simply begin with a <quote><literal>q</literal></quote>.  The exceptions "
 1.15121 +"are quilt's <literal>add</literal> and <literal>remove</literal> commands, "
 1.15122 +"the counterparts for which are the normal Mercurial <command role=\"hg-cmd"
 1.15123 +"\">hg add</command> and <command role=\"hg-cmd\">hg remove</command> "
 1.15124 +"commands.  There is no MQ equivalent of the quilt <literal>edit</literal> "
 1.15125 +"command."
 1.15126 +msgstr ""
 1.15127 +
 1.15128 +#. type: Content of: <book><chapter><title>
 1.15129 +#: ../en/ch13-mq-collab.xml:5
 1.15130 +msgid "Advanced uses of Mercurial Queues"
 1.15131 +msgstr "MQ 的高级用法"
 1.15132 +
 1.15133 +#. type: Content of: <book><chapter><para>
 1.15134 +#: ../en/ch13-mq-collab.xml:7
 1.15135 +msgid ""
 1.15136 +"While it's easy to pick up straightforward uses of Mercurial Queues, use of a "
 1.15137 +"little discipline and some of MQ's less frequently used capabilities makes it "
 1.15138 +"possible to work in complicated development environments."
 1.15139 +msgstr ""
 1.15140 +
 1.15141 +#. type: Content of: <book><chapter><para>
 1.15142 +#: ../en/ch13-mq-collab.xml:12
 1.15143 +msgid ""
 1.15144 +"In this chapter, I will use as an example a technique I have used to manage "
 1.15145 +"the development of an Infiniband device driver for the Linux kernel.  The "
 1.15146 +"driver in question is large (at least as drivers go), with 25,000 lines of "
 1.15147 +"code spread across 35 source files.  It is maintained by a small team of "
 1.15148 +"developers."
 1.15149 +msgstr ""
 1.15150 +
 1.15151 +#. type: Content of: <book><chapter><para>
 1.15152 +#: ../en/ch13-mq-collab.xml:18
 1.15153 +msgid ""
 1.15154 +"While much of the material in this chapter is specific to Linux, the same "
 1.15155 +"principles apply to any code base for which you're not the primary owner, and "
 1.15156 +"upon which you need to do a lot of development."
 1.15157 +msgstr ""
 1.15158 +
 1.15159 +#. type: Content of: <book><chapter><sect1><title>
 1.15160 +#: ../en/ch13-mq-collab.xml:24
 1.15161 +msgid "The problem of many targets"
 1.15162 +msgstr ""
 1.15163 +
 1.15164 +#. type: Content of: <book><chapter><sect1><para>
 1.15165 +#: ../en/ch13-mq-collab.xml:26
 1.15166 +msgid ""
 1.15167 +"The Linux kernel changes rapidly, and has never been internally stable; "
 1.15168 +"developers frequently make drastic changes between releases. This means that "
 1.15169 +"a version of the driver that works well with a particular released version of "
 1.15170 +"the kernel will not even <emphasis>compile</emphasis> correctly against, "
 1.15171 +"typically, any other version."
 1.15172 +msgstr ""
 1.15173 +
 1.15174 +#. type: Content of: <book><chapter><sect1><para>
 1.15175 +#: ../en/ch13-mq-collab.xml:33
 1.15176 +msgid ""
 1.15177 +"To maintain a driver, we have to keep a number of distinct versions of Linux "
 1.15178 +"in mind."
 1.15179 +msgstr ""
 1.15180 +
 1.15181 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15182 +#: ../en/ch13-mq-collab.xml:36
 1.15183 +msgid ""
 1.15184 +"One target is the main Linux kernel development tree. Maintenance of the code "
 1.15185 +"is in this case partly shared by other developers in the kernel community, "
 1.15186 +"who make <quote>drive-by</quote> modifications to the driver as they develop "
 1.15187 +"and refine kernel subsystems."
 1.15188 +msgstr ""
 1.15189 +
 1.15190 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15191 +#: ../en/ch13-mq-collab.xml:42
 1.15192 +msgid ""
 1.15193 +"We also maintain a number of <quote>backports</quote> to older versions of "
 1.15194 +"the Linux kernel, to support the needs of customers who are running older "
 1.15195 +"Linux distributions that do not incorporate our drivers.  (To "
 1.15196 +"<emphasis>backport</emphasis> a piece of code is to modify it to work in an "
 1.15197 +"older version of its target environment than the version it was developed "
 1.15198 +"for.)"
 1.15199 +msgstr ""
 1.15200 +
 1.15201 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15202 +#: ../en/ch13-mq-collab.xml:50
 1.15203 +msgid ""
 1.15204 +"Finally, we make software releases on a schedule that is necessarily not "
 1.15205 +"aligned with those used by Linux distributors and kernel developers, so that "
 1.15206 +"we can deliver new features to customers without forcing them to upgrade "
 1.15207 +"their entire kernels or distributions."
 1.15208 +msgstr ""
 1.15209 +
 1.15210 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.15211 +#: ../en/ch13-mq-collab.xml:58
 1.15212 +msgid "Tempting approaches that don't work well"
 1.15213 +msgstr ""
 1.15214 +
 1.15215 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15216 +#: ../en/ch13-mq-collab.xml:60
 1.15217 +msgid ""
 1.15218 +"There are two <quote>standard</quote> ways to maintain a piece of software "
 1.15219 +"that has to target many different environments."
 1.15220 +msgstr ""
 1.15221 +
 1.15222 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15223 +#: ../en/ch13-mq-collab.xml:64
 1.15224 +msgid ""
 1.15225 +"The first is to maintain a number of branches, each intended for a single "
 1.15226 +"target.  The trouble with this approach is that you must maintain iron "
 1.15227 +"discipline in the flow of changes between repositories. A new feature or bug "
 1.15228 +"fix must start life in a <quote>pristine</quote> repository, then percolate "
 1.15229 +"out to every backport repository.  Backport changes are more limited in the "
 1.15230 +"branches they should propagate to; a backport change that is applied to a "
 1.15231 +"branch where it doesn't belong will probably stop the driver from compiling."
 1.15232 +msgstr ""
 1.15233 +
 1.15234 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15235 +#: ../en/ch13-mq-collab.xml:74
 1.15236 +msgid ""
 1.15237 +"The second is to maintain a single source tree filled with conditional "
 1.15238 +"statements that turn chunks of code on or off depending on the intended "
 1.15239 +"target.  Because these <quote>ifdefs</quote> are not allowed in the Linux "
 1.15240 +"kernel tree, a manual or automatic process must be followed to strip them out "
 1.15241 +"and yield a clean tree.  A code base maintained in this fashion rapidly "
 1.15242 +"becomes a rat's nest of conditional blocks that are difficult to understand "
 1.15243 +"and maintain."
 1.15244 +msgstr ""
 1.15245 +
 1.15246 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15247 +#: ../en/ch13-mq-collab.xml:83
 1.15248 +msgid ""
 1.15249 +"Neither of these approaches is well suited to a situation where you don't "
 1.15250 +"<quote>own</quote> the canonical copy of a source tree.  In the case of a "
 1.15251 +"Linux driver that is distributed with the standard kernel, Linus's tree "
 1.15252 +"contains the copy of the code that will be treated by the world as "
 1.15253 +"canonical.  The upstream version of <quote>my</quote> driver can be modified "
 1.15254 +"by people I don't know, without me even finding out about it until after the "
 1.15255 +"changes show up in Linus's tree."
 1.15256 +msgstr ""
 1.15257 +
 1.15258 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15259 +#: ../en/ch13-mq-collab.xml:93
 1.15260 +msgid ""
 1.15261 +"These approaches have the added weakness of making it difficult to generate "
 1.15262 +"well-formed patches to submit upstream."
 1.15263 +msgstr ""
 1.15264 +
 1.15265 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15266 +#: ../en/ch13-mq-collab.xml:97
 1.15267 +msgid ""
 1.15268 +"In principle, Mercurial Queues seems like a good candidate to manage a "
 1.15269 +"development scenario such as the above.  While this is indeed the case, MQ "
 1.15270 +"contains a few added features that make the job more pleasant."
 1.15271 +msgstr ""
 1.15272 +
 1.15273 +#. type: Content of: <book><chapter><sect1><title>
 1.15274 +#: ../en/ch13-mq-collab.xml:105
 1.15275 +msgid "Conditionally applying patches with guards"
 1.15276 +msgstr ""
 1.15277 +
 1.15278 +#. type: Content of: <book><chapter><sect1><para>
 1.15279 +#: ../en/ch13-mq-collab.xml:107
 1.15280 +msgid ""
 1.15281 +"Perhaps the best way to maintain sanity with so many targets is to be able to "
 1.15282 +"choose specific patches to apply for a given situation.  MQ provides a "
 1.15283 +"feature called <quote>guards</quote> (which originates with quilt's "
 1.15284 +"<literal>guards</literal> command) that does just this.  To start off, let's "
 1.15285 +"create a simple repository for experimenting in."
 1.15286 +msgstr ""
 1.15287 +
 1.15288 +#. type: Content of: <book><chapter><sect1><para>
 1.15289 +#: ../en/ch13-mq-collab.xml:116
 1.15290 +msgid ""
 1.15291 +"This gives us a tiny repository that contains two patches that don't have any "
 1.15292 +"dependencies on each other, because they touch different files."
 1.15293 +msgstr ""
 1.15294 +
 1.15295 +#. type: Content of: <book><chapter><sect1><para>
 1.15296 +#: ../en/ch13-mq-collab.xml:120
 1.15297 +msgid ""
 1.15298 +"The idea behind conditional application is that you can <quote>tag</quote> a "
 1.15299 +"patch with a <emphasis>guard</emphasis>, which is simply a text string of "
 1.15300 +"your choosing, then tell MQ to select specific guards to use when applying "
 1.15301 +"patches.  MQ will then either apply, or skip over, a guarded patch, depending "
 1.15302 +"on the guards that you have selected."
 1.15303 +msgstr ""
 1.15304 +
 1.15305 +#. type: Content of: <book><chapter><sect1><para>
 1.15306 +#: ../en/ch13-mq-collab.xml:127
 1.15307 +msgid ""
 1.15308 +"A patch can have an arbitrary number of guards; each one is "
 1.15309 +"<emphasis>positive</emphasis> (<quote>apply this patch if this guard is "
 1.15310 +"selected</quote>) or <emphasis>negative</emphasis> (<quote>skip this patch if "
 1.15311 +"this guard is selected</quote>).  A patch with no guards is always applied."
 1.15312 +msgstr ""
 1.15313 +
 1.15314 +#. type: Content of: <book><chapter><sect1><title>
 1.15315 +#: ../en/ch13-mq-collab.xml:135
 1.15316 +msgid "Controlling the guards on a patch"
 1.15317 +msgstr ""
 1.15318 +
 1.15319 +#. type: Content of: <book><chapter><sect1><para>
 1.15320 +#: ../en/ch13-mq-collab.xml:137
 1.15321 +msgid ""
 1.15322 +"The <command role=\"hg-ext-mq\">qguard</command> command lets you determine "
 1.15323 +"which guards should apply to a patch, or display the guards that are already "
 1.15324 +"in effect. Without any arguments, it displays the guards on the current "
 1.15325 +"topmost patch."
 1.15326 +msgstr ""
 1.15327 +
 1.15328 +#. type: Content of: <book><chapter><sect1><para>
 1.15329 +#: ../en/ch13-mq-collab.xml:144
 1.15330 +msgid ""
 1.15331 +"To set a positive guard on a patch, prefix the name of the guard with a "
 1.15332 +"<quote><literal>+</literal></quote>."
 1.15333 +msgstr ""
 1.15334 +
 1.15335 +#. type: Content of: <book><chapter><sect1><para>
 1.15336 +#: ../en/ch13-mq-collab.xml:149
 1.15337 +msgid ""
 1.15338 +"To set a negative guard on a patch, prefix the name of the guard with a "
 1.15339 +"<quote><literal>-</literal></quote>."
 1.15340 +msgstr ""
 1.15341 +
 1.15342 +#. type: Content of: <book><chapter><sect1><note><para>
 1.15343 +#: ../en/ch13-mq-collab.xml:156
 1.15344 +msgid ""
 1.15345 +"The <command role=\"hg-ext-mq\">qguard</command> command <emphasis>sets</"
 1.15346 +"emphasis> the guards on a patch; it doesn't <emphasis>modify</emphasis> "
 1.15347 +"them.  What this means is that if you run <command role=\"hg-cmd\">hg qguard "
 1.15348 +"+a +b</command> on a patch, then <command role=\"hg-cmd\">hg qguard +c</"
 1.15349 +"command> on the same patch, the <emphasis>only</emphasis> guard that will be "
 1.15350 +"set on it afterwards is <literal>+c</literal>."
 1.15351 +msgstr ""
 1.15352 +
 1.15353 +#
 1.15354 +#. type: Content of: <book><chapter><sect1><para>
 1.15355 +#: ../en/ch13-mq-collab.xml:165
 1.15356 +msgid ""
 1.15357 +"Mercurial stores guards in the <filename role=\"special\">series</filename> "
 1.15358 +"file; the form in which they are stored is easy both to understand and to "
 1.15359 +"edit by hand. (In other words, you don't have to use the <command role=\"hg-"
 1.15360 +"ext-mq\">qguard</command> command if you don't want to; it's okay to simply "
 1.15361 +"edit the <filename role=\"special\">series</filename> file.)"
 1.15362 +msgstr ""
 1.15363 +
 1.15364 +#. type: Content of: <book><chapter><sect1><title>
 1.15365 +#: ../en/ch13-mq-collab.xml:177
 1.15366 +msgid "Selecting the guards to use"
 1.15367 +msgstr ""
 1.15368 +
 1.15369 +#. type: Content of: <book><chapter><sect1><para>
 1.15370 +#: ../en/ch13-mq-collab.xml:179
 1.15371 +msgid ""
 1.15372 +"The <command role=\"hg-ext-mq\">qselect</command> command determines which "
 1.15373 +"guards are active at a given time.  The effect of this is to determine which "
 1.15374 +"patches MQ will apply the next time you run <command role=\"hg-ext-mq"
 1.15375 +"\">qpush</command>.  It has no other effect; in particular, it doesn't do "
 1.15376 +"anything to patches that are already applied."
 1.15377 +msgstr ""
 1.15378 +
 1.15379 +#. type: Content of: <book><chapter><sect1><para>
 1.15380 +#: ../en/ch13-mq-collab.xml:186
 1.15381 +msgid ""
 1.15382 +"With no arguments, the <command role=\"hg-ext-mq\">qselect</command> command "
 1.15383 +"lists the guards currently in effect, one per line of output.  Each argument "
 1.15384 +"is treated as the name of a guard to apply."
 1.15385 +msgstr ""
 1.15386 +
 1.15387 +#. type: Content of: <book><chapter><sect1><para>
 1.15388 +#: ../en/ch13-mq-collab.xml:193
 1.15389 +msgid ""
 1.15390 +"In case you're interested, the currently selected guards are stored in the "
 1.15391 +"<filename role=\"special\">guards</filename> file."
 1.15392 +msgstr ""
 1.15393 +
 1.15394 +#. type: Content of: <book><chapter><sect1><para>
 1.15395 +#: ../en/ch13-mq-collab.xml:198
 1.15396 +msgid ""
 1.15397 +"We can see the effect the selected guards have when we run <command role=\"hg-"
 1.15398 +"ext-mq\">qpush</command>."
 1.15399 +msgstr ""
 1.15400 +
 1.15401 +#. type: Content of: <book><chapter><sect1><para>
 1.15402 +#: ../en/ch13-mq-collab.xml:203
 1.15403 +msgid ""
 1.15404 +"A guard cannot start with a <quote><literal>+</literal></quote> or "
 1.15405 +"<quote><literal>-</literal></quote> character.  The name of a guard must not "
 1.15406 +"contain white space, but most other characters are acceptable.  If you try to "
 1.15407 +"use a guard with an invalid name, MQ will complain:"
 1.15408 +msgstr ""
 1.15409 +
 1.15410 +#. type: Content of: <book><chapter><sect1><para>
 1.15411 +#: ../en/ch13-mq-collab.xml:212
 1.15412 +msgid "Changing the selected guards changes the patches that are applied."
 1.15413 +msgstr ""
 1.15414 +
 1.15415 +#. type: Content of: <book><chapter><sect1><para>
 1.15416 +#: ../en/ch13-mq-collab.xml:217
 1.15417 +msgid ""
 1.15418 +"You can see in the example below that negative guards take precedence over "
 1.15419 +"positive guards."
 1.15420 +msgstr ""
 1.15421 +
 1.15422 +#. type: Content of: <book><chapter><sect1><title>
 1.15423 +#: ../en/ch13-mq-collab.xml:224
 1.15424 +msgid "MQ's rules for applying patches"
 1.15425 +msgstr ""
 1.15426 +
 1.15427 +#. type: Content of: <book><chapter><sect1><para>
 1.15428 +#: ../en/ch13-mq-collab.xml:226
 1.15429 +msgid ""
 1.15430 +"The rules that MQ uses when deciding whether to apply a patch are as follows."
 1.15431 +msgstr ""
 1.15432 +
 1.15433 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15434 +#: ../en/ch13-mq-collab.xml:229
 1.15435 +msgid "A patch that has no guards is always applied."
 1.15436 +msgstr ""
 1.15437 +
 1.15438 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15439 +#: ../en/ch13-mq-collab.xml:232
 1.15440 +msgid ""
 1.15441 +"If the patch has any negative guard that matches any currently selected "
 1.15442 +"guard, the patch is skipped."
 1.15443 +msgstr ""
 1.15444 +
 1.15445 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15446 +#: ../en/ch13-mq-collab.xml:235
 1.15447 +msgid ""
 1.15448 +"If the patch has any positive guard that matches any currently selected "
 1.15449 +"guard, the patch is applied."
 1.15450 +msgstr ""
 1.15451 +
 1.15452 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15453 +#: ../en/ch13-mq-collab.xml:238
 1.15454 +msgid ""
 1.15455 +"If the patch has positive or negative guards, but none matches any currently "
 1.15456 +"selected guard, the patch is skipped."
 1.15457 +msgstr ""
 1.15458 +
 1.15459 +#. type: Content of: <book><chapter><sect1><title>
 1.15460 +#: ../en/ch13-mq-collab.xml:245
 1.15461 +msgid "Trimming the work environment"
 1.15462 +msgstr ""
 1.15463 +
 1.15464 +#. type: Content of: <book><chapter><sect1><para>
 1.15465 +#: ../en/ch13-mq-collab.xml:247
 1.15466 +msgid ""
 1.15467 +"In working on the device driver I mentioned earlier, I don't apply the "
 1.15468 +"patches to a normal Linux kernel tree.  Instead, I use a repository that "
 1.15469 +"contains only a snapshot of the source files and headers that are relevant to "
 1.15470 +"Infiniband development.  This repository is 1% the size of a kernel "
 1.15471 +"repository, so it's easier to work with."
 1.15472 +msgstr ""
 1.15473 +
 1.15474 +#. type: Content of: <book><chapter><sect1><para>
 1.15475 +#: ../en/ch13-mq-collab.xml:254
 1.15476 +msgid ""
 1.15477 +"I then choose a <quote>base</quote> version on top of which the patches are "
 1.15478 +"applied.  This is a snapshot of the Linux kernel tree as of a revision of my "
 1.15479 +"choosing.  When I take the snapshot, I record the changeset ID from the "
 1.15480 +"kernel repository in the commit message.  Since the snapshot preserves the "
 1.15481 +"<quote>shape</quote> and content of the relevant parts of the kernel tree, I "
 1.15482 +"can apply my patches on top of either my tiny repository or a normal kernel "
 1.15483 +"tree."
 1.15484 +msgstr ""
 1.15485 +
 1.15486 +#. type: Content of: <book><chapter><sect1><para>
 1.15487 +#: ../en/ch13-mq-collab.xml:263
 1.15488 +msgid ""
 1.15489 +"Normally, the base tree atop which the patches apply should be a snapshot of "
 1.15490 +"a very recent upstream tree.  This best facilitates the development of "
 1.15491 +"patches that can easily be submitted upstream with few or no modifications."
 1.15492 +msgstr ""
 1.15493 +
 1.15494 +#. type: Content of: <book><chapter><sect1><title>
 1.15495 +#: ../en/ch13-mq-collab.xml:270
 1.15496 +msgid "Dividing up the <filename role=\"special\">series</filename> file"
 1.15497 +msgstr ""
 1.15498 +
 1.15499 +#. type: Content of: <book><chapter><sect1><para>
 1.15500 +#: ../en/ch13-mq-collab.xml:273
 1.15501 +msgid ""
 1.15502 +"I categorise the patches in the <filename role=\"special\">series</filename> "
 1.15503 +"file into a number of logical groups.  Each section of like patches begins "
 1.15504 +"with a block of comments that describes the purpose of the patches that "
 1.15505 +"follow."
 1.15506 +msgstr ""
 1.15507 +
 1.15508 +#. type: Content of: <book><chapter><sect1><para>
 1.15509 +#: ../en/ch13-mq-collab.xml:279
 1.15510 +msgid ""
 1.15511 +"The sequence of patch groups that I maintain follows.  The ordering of these "
 1.15512 +"groups is important; I'll describe why after I introduce the groups."
 1.15513 +msgstr ""
 1.15514 +
 1.15515 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15516 +#: ../en/ch13-mq-collab.xml:283
 1.15517 +msgid ""
 1.15518 +"The <quote>accepted</quote> group.  Patches that the development team has "
 1.15519 +"submitted to the maintainer of the Infiniband subsystem, and which he has "
 1.15520 +"accepted, but which are not present in the snapshot that the tiny repository "
 1.15521 +"is based on.  These are <quote>read only</quote> patches, present only to "
 1.15522 +"transform the tree into a similar state as it is in the upstream maintainer's "
 1.15523 +"repository."
 1.15524 +msgstr ""
 1.15525 +
 1.15526 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15527 +#: ../en/ch13-mq-collab.xml:291
 1.15528 +msgid ""
 1.15529 +"The <quote>rework</quote> group.  Patches that I have submitted, but that the "
 1.15530 +"upstream maintainer has requested modifications to before he will accept them."
 1.15531 +msgstr ""
 1.15532 +
 1.15533 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15534 +#: ../en/ch13-mq-collab.xml:296
 1.15535 +msgid ""
 1.15536 +"The <quote>pending</quote> group.  Patches that I have not yet submitted to "
 1.15537 +"the upstream maintainer, but which we have finished working on. These will be "
 1.15538 +"<quote>read only</quote> for a while.  If the upstream maintainer accepts "
 1.15539 +"them upon submission, I'll move them to the end of the <quote>accepted</"
 1.15540 +"quote> group.  If he requests that I modify any, I'll move them to the "
 1.15541 +"beginning of the <quote>rework</quote> group."
 1.15542 +msgstr ""
 1.15543 +
 1.15544 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15545 +#: ../en/ch13-mq-collab.xml:305
 1.15546 +msgid ""
 1.15547 +"The <quote>in progress</quote> group.  Patches that are actively being "
 1.15548 +"developed, and should not be submitted anywhere yet."
 1.15549 +msgstr ""
 1.15550 +
 1.15551 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15552 +#: ../en/ch13-mq-collab.xml:309
 1.15553 +msgid ""
 1.15554 +"The <quote>backport</quote> group.  Patches that adapt the source tree to "
 1.15555 +"older versions of the kernel tree."
 1.15556 +msgstr ""
 1.15557 +
 1.15558 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15559 +#: ../en/ch13-mq-collab.xml:313
 1.15560 +msgid ""
 1.15561 +"The <quote>do not ship</quote> group.  Patches that for some reason should "
 1.15562 +"never be submitted upstream.  For example, one such patch might change "
 1.15563 +"embedded driver identification strings to make it easier to distinguish, in "
 1.15564 +"the field, between an out-of-tree version of the driver and a version shipped "
 1.15565 +"by a distribution vendor."
 1.15566 +msgstr ""
 1.15567 +
 1.15568 +#. type: Content of: <book><chapter><sect1><para>
 1.15569 +#: ../en/ch13-mq-collab.xml:321
 1.15570 +msgid ""
 1.15571 +"Now to return to the reasons for ordering groups of patches in this way.  We "
 1.15572 +"would like the lowest patches in the stack to be as stable as possible, so "
 1.15573 +"that we will not need to rework higher patches due to changes in context.  "
 1.15574 +"Putting patches that will never be changed first in the <filename role="
 1.15575 +"\"special\">series</filename> file serves this purpose."
 1.15576 +msgstr ""
 1.15577 +
 1.15578 +#. type: Content of: <book><chapter><sect1><para>
 1.15579 +#: ../en/ch13-mq-collab.xml:329
 1.15580 +msgid ""
 1.15581 +"We would also like the patches that we know we'll need to modify to be "
 1.15582 +"applied on top of a source tree that resembles the upstream tree as closely "
 1.15583 +"as possible.  This is why we keep accepted patches around for a while."
 1.15584 +msgstr ""
 1.15585 +
 1.15586 +#. type: Content of: <book><chapter><sect1><para>
 1.15587 +#: ../en/ch13-mq-collab.xml:334
 1.15588 +msgid ""
 1.15589 +"The <quote>backport</quote> and <quote>do not ship</quote> patches float at "
 1.15590 +"the end of the <filename role=\"special\">series</filename> file.  The "
 1.15591 +"backport patches must be applied on top of all other patches, and the "
 1.15592 +"<quote>do not ship</quote> patches might as well stay out of harm's way."
 1.15593 +msgstr ""
 1.15594 +
 1.15595 +#. type: Content of: <book><chapter><sect1><title>
 1.15596 +#: ../en/ch13-mq-collab.xml:343
 1.15597 +msgid "Maintaining the patch series"
 1.15598 +msgstr ""
 1.15599 +
 1.15600 +#. type: Content of: <book><chapter><sect1><para>
 1.15601 +#: ../en/ch13-mq-collab.xml:345
 1.15602 +msgid ""
 1.15603 +"In my work, I use a number of guards to control which patches are to be "
 1.15604 +"applied."
 1.15605 +msgstr ""
 1.15606 +
 1.15607 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15608 +#: ../en/ch13-mq-collab.xml:349
 1.15609 +msgid ""
 1.15610 +"<quote>Accepted</quote> patches are guarded with <literal>accepted</"
 1.15611 +"literal>.  I enable this guard most of the time.  When I'm applying the "
 1.15612 +"patches on top of a tree where the patches are already present, I can turn "
 1.15613 +"this patch off, and the patches that follow it will apply cleanly."
 1.15614 +msgstr ""
 1.15615 +
 1.15616 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15617 +#: ../en/ch13-mq-collab.xml:356
 1.15618 +msgid ""
 1.15619 +"Patches that are <quote>finished</quote>, but not yet submitted, have no "
 1.15620 +"guards.  If I'm applying the patch stack to a copy of the upstream tree, I "
 1.15621 +"don't need to enable any guards in order to get a reasonably safe source tree."
 1.15622 +msgstr ""
 1.15623 +
 1.15624 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15625 +#: ../en/ch13-mq-collab.xml:362
 1.15626 +msgid ""
 1.15627 +"Those patches that need reworking before being resubmitted are guarded with "
 1.15628 +"<literal>rework</literal>."
 1.15629 +msgstr ""
 1.15630 +
 1.15631 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15632 +#: ../en/ch13-mq-collab.xml:366
 1.15633 +msgid ""
 1.15634 +"For those patches that are still under development, I use <literal>devel</"
 1.15635 +"literal>."
 1.15636 +msgstr ""
 1.15637 +
 1.15638 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15639 +#: ../en/ch13-mq-collab.xml:369
 1.15640 +msgid ""
 1.15641 +"A backport patch may have several guards, one for each version of the kernel "
 1.15642 +"to which it applies.  For example, a patch that backports a piece of code to "
 1.15643 +"2.6.9 will have a <literal>2.6.9</literal> guard."
 1.15644 +msgstr ""
 1.15645 +
 1.15646 +#. type: Content of: <book><chapter><sect1><para>
 1.15647 +#: ../en/ch13-mq-collab.xml:374
 1.15648 +msgid ""
 1.15649 +"This variety of guards gives me considerable flexibility in determining what "
 1.15650 +"kind of source tree I want to end up with.  For most situations, the "
 1.15651 +"selection of appropriate guards is automated during the build process, but I "
 1.15652 +"can manually tune the guards to use for less common circumstances."
 1.15653 +msgstr ""
 1.15654 +
 1.15655 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.15656 +#: ../en/ch13-mq-collab.xml:381
 1.15657 +msgid "The art of writing backport patches"
 1.15658 +msgstr ""
 1.15659 +
 1.15660 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15661 +#: ../en/ch13-mq-collab.xml:383
 1.15662 +msgid ""
 1.15663 +"Using MQ, writing a backport patch is a simple process.  All such a patch has "
 1.15664 +"to do is modify a piece of code that uses a kernel feature not present in the "
 1.15665 +"older version of the kernel, so that the driver continues to work correctly "
 1.15666 +"under that older version."
 1.15667 +msgstr ""
 1.15668 +
 1.15669 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15670 +#: ../en/ch13-mq-collab.xml:389
 1.15671 +msgid ""
 1.15672 +"A useful goal when writing a good backport patch is to make your code look as "
 1.15673 +"if it was written for the older version of the kernel you're targeting.  The "
 1.15674 +"less obtrusive the patch, the easier it will be to understand and maintain.  "
 1.15675 +"If you're writing a collection of backport patches to avoid the <quote>rat's "
 1.15676 +"nest</quote> effect of lots of <literal>#ifdef</literal>s (hunks of source "
 1.15677 +"code that are only used conditionally) in your code, don't introduce version-"
 1.15678 +"dependent <literal>#ifdef</literal>s into the patches.  Instead, write "
 1.15679 +"several patches, each of which makes unconditional changes, and control their "
 1.15680 +"application using guards."
 1.15681 +msgstr ""
 1.15682 +
 1.15683 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15684 +#: ../en/ch13-mq-collab.xml:402
 1.15685 +msgid ""
 1.15686 +"There are two reasons to divide backport patches into a distinct group, away "
 1.15687 +"from the <quote>regular</quote> patches whose effects they modify. The first "
 1.15688 +"is that intermingling the two makes it more difficult to use a tool like the "
 1.15689 +"<literal role=\"hg-ext\">patchbomb</literal> extension to automate the "
 1.15690 +"process of submitting the patches to an upstream maintainer.  The second is "
 1.15691 +"that a backport patch could perturb the context in which a subsequent regular "
 1.15692 +"patch is applied, making it impossible to apply the regular patch cleanly "
 1.15693 +"<emphasis>without</emphasis> the earlier backport patch already being applied."
 1.15694 +msgstr ""
 1.15695 +
 1.15696 +#. type: Content of: <book><chapter><sect1><title>
 1.15697 +#: ../en/ch13-mq-collab.xml:417
 1.15698 +msgid "Useful tips for developing with MQ"
 1.15699 +msgstr ""
 1.15700 +
 1.15701 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.15702 +#: ../en/ch13-mq-collab.xml:420
 1.15703 +msgid "Organising patches in directories"
 1.15704 +msgstr ""
 1.15705 +
 1.15706 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15707 +#: ../en/ch13-mq-collab.xml:422
 1.15708 +msgid ""
 1.15709 +"If you're working on a substantial project with MQ, it's not difficult to "
 1.15710 +"accumulate a large number of patches.  For example, I have one patch "
 1.15711 +"repository that contains over 250 patches."
 1.15712 +msgstr ""
 1.15713 +
 1.15714 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15715 +#: ../en/ch13-mq-collab.xml:427
 1.15716 +msgid ""
 1.15717 +"If you can group these patches into separate logical categories, you can if "
 1.15718 +"you like store them in different directories; MQ has no problems with patch "
 1.15719 +"names that contain path separators."
 1.15720 +msgstr ""
 1.15721 +
 1.15722 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.15723 +#: ../en/ch13-mq-collab.xml:434
 1.15724 +msgid "Viewing the history of a patch"
 1.15725 +msgstr ""
 1.15726 +
 1.15727 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15728 +#: ../en/ch13-mq-collab.xml:436
 1.15729 +msgid ""
 1.15730 +"If you're developing a set of patches over a long time, it's a good idea to "
 1.15731 +"maintain them in a repository, as discussed in section <xref linkend=\"sec.mq."
 1.15732 +"repo\"/>.  If you do so, you'll quickly discover that using the <command role="
 1.15733 +"\"hg-cmd\">hg diff</command> command to look at the history of changes to a "
 1.15734 +"patch is unworkable.  This is in part because you're looking at the second "
 1.15735 +"derivative of the real code (a diff of a diff), but also because MQ adds "
 1.15736 +"noise to the process by modifying time stamps and directory names when it "
 1.15737 +"updates a patch."
 1.15738 +msgstr ""
 1.15739 +
 1.15740 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15741 +#: ../en/ch13-mq-collab.xml:448
 1.15742 +msgid ""
 1.15743 +"However, you can use the <literal role=\"hg-ext\">extdiff</literal> "
 1.15744 +"extension, which is bundled with Mercurial, to turn a diff of two versions of "
 1.15745 +"a patch into something readable.  To do this, you will need a third-party "
 1.15746 +"package called <literal role=\"package\">patchutils</literal> <citation>web:"
 1.15747 +"patchutils</citation>.  This provides a command named <command>interdiff</"
 1.15748 +"command>, which shows the differences between two diffs as a diff.  Used on "
 1.15749 +"two versions of the same diff, it generates a diff that represents the diff "
 1.15750 +"from the first to the second version."
 1.15751 +msgstr ""
 1.15752 +
 1.15753 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15754 +#: ../en/ch13-mq-collab.xml:459
 1.15755 +msgid ""
 1.15756 +"You can enable the <literal role=\"hg-ext\">extdiff</literal> extension in "
 1.15757 +"the usual way, by adding a line to the <literal role=\"rc-extensions"
 1.15758 +"\">extensions</literal> section of your <filename role=\"special\"> /.hgrc</"
 1.15759 +"filename>."
 1.15760 +msgstr ""
 1.15761 +
 1.15762 +#
 1.15763 +#. 	&example.hg-interdiff; 
 1.15764 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15765 +#: ../en/ch13-mq-collab.xml:465
 1.15766 +msgid ""
 1.15767 +"The <command>interdiff</command> command expects to be passed the names of "
 1.15768 +"two files, but the <literal role=\"hg-ext\">extdiff</literal> extension "
 1.15769 +"passes the program it runs a pair of directories, each of which can contain "
 1.15770 +"an arbitrary number of files.  We thus need a small program that will run "
 1.15771 +"<command>interdiff</command> on each pair of files in these two directories.  "
 1.15772 +"This program is available as <filename role=\"special\">hg-interdiff</"
 1.15773 +"filename> in the <filename class=\"directory\">examples</filename> directory "
 1.15774 +"of the source code repository that accompanies this book."
 1.15775 +msgstr ""
 1.15776 +
 1.15777 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15778 +#: ../en/ch13-mq-collab.xml:477
 1.15779 +msgid ""
 1.15780 +"With the <filename role=\"special\">hg-interdiff</filename> program in your "
 1.15781 +"shell's search path, you can run it as follows, from inside an MQ patch "
 1.15782 +"directory:"
 1.15783 +msgstr ""
 1.15784 +
 1.15785 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15786 +#: ../en/ch13-mq-collab.xml:482
 1.15787 +msgid ""
 1.15788 +"Since you'll probably want to use this long-winded command a lot, you can get "
 1.15789 +"<literal role=\"hg-ext\">hgext</literal> to make it available as a normal "
 1.15790 +"Mercurial command, again by editing your <filename role=\"special\"> /.hgrc</"
 1.15791 +"filename>."
 1.15792 +msgstr ""
 1.15793 +
 1.15794 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15795 +#: ../en/ch13-mq-collab.xml:489
 1.15796 +msgid ""
 1.15797 +"This directs <literal role=\"hg-ext\">hgext</literal> to make an "
 1.15798 +"<literal>interdiff</literal> command available, so you can now shorten the "
 1.15799 +"previous invocation of <command role=\"hg-ext-extdiff\">extdiff</command> to "
 1.15800 +"something a little more wieldy."
 1.15801 +msgstr ""
 1.15802 +
 1.15803 +#. type: Content of: <book><chapter><sect1><sect2><note><para>
 1.15804 +#: ../en/ch13-mq-collab.xml:498
 1.15805 +msgid ""
 1.15806 +"The <command>interdiff</command> command works well only if the underlying "
 1.15807 +"files against which versions of a patch are generated remain the same.  If "
 1.15808 +"you create a patch, modify the underlying files, and then regenerate the "
 1.15809 +"patch, <command>interdiff</command> may not produce useful output."
 1.15810 +msgstr ""
 1.15811 +
 1.15812 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.15813 +#: ../en/ch13-mq-collab.xml:506
 1.15814 +msgid ""
 1.15815 +"The <literal role=\"hg-ext\">extdiff</literal> extension is useful for more "
 1.15816 +"than merely improving the presentation of MQ patches.  To read more about it, "
 1.15817 +"go to section <xref linkend=\"sec.hgext.extdiff\"/>."
 1.15818 +msgstr ""
 1.15819 +
 1.15820 +#. type: Content of: <book><chapter><title>
 1.15821 +#: ../en/ch14-hgext.xml:5
 1.15822 +msgid "Adding functionality with extensions"
 1.15823 +msgstr "使用扩展增加功能"
 1.15824 +
 1.15825 +#. type: Content of: <book><chapter><para>
 1.15826 +#: ../en/ch14-hgext.xml:7
 1.15827 +msgid ""
 1.15828 +"While the core of Mercurial is quite complete from a functionality "
 1.15829 +"standpoint, it's deliberately shorn of fancy features.  This approach of "
 1.15830 +"preserving simplicity keeps the software easy to deal with for both "
 1.15831 +"maintainers and users."
 1.15832 +msgstr ""
 1.15833 +
 1.15834 +#. type: Content of: <book><chapter><para>
 1.15835 +#: ../en/ch14-hgext.xml:12
 1.15836 +msgid ""
 1.15837 +"However, Mercurial doesn't box you in with an inflexible command set: you can "
 1.15838 +"add features to it as <emphasis>extensions</emphasis> (sometimes known as "
 1.15839 +"<emphasis>plugins</emphasis>).  We've already discussed a few of these "
 1.15840 +"extensions in earlier chapters."
 1.15841 +msgstr ""
 1.15842 +
 1.15843 +#. type: Content of: <book><chapter><itemizedlist><listitem><para>
 1.15844 +#: ../en/ch14-hgext.xml:18
 1.15845 +msgid ""
 1.15846 +"Section <xref linkend=\"sec.tour-merge.fetch\"/> covers the <literal role="
 1.15847 +"\"hg-ext\">fetch</literal> extension; this combines pulling new changes and "
 1.15848 +"merging them with local changes into a single command, <command role=\"hg-ext-"
 1.15849 +"fetch\">fetch</command>."
 1.15850 +msgstr ""
 1.15851 +
 1.15852 +#. type: Content of: <book><chapter><itemizedlist><listitem><para>
 1.15853 +#: ../en/ch14-hgext.xml:24
 1.15854 +msgid ""
 1.15855 +"In chapter <xref linkend=\"chap.hook\"/>, we covered several extensions that "
 1.15856 +"are useful for hook-related functionality: <literal role=\"hg-ext\">acl</"
 1.15857 +"literal> adds access control lists; <literal role=\"hg-ext\">bugzilla</"
 1.15858 +"literal> adds integration with the Bugzilla bug tracking system; and <literal "
 1.15859 +"role=\"hg-ext\">notify</literal> sends notification emails on new changes."
 1.15860 +msgstr ""
 1.15861 +
 1.15862 +#. type: Content of: <book><chapter><itemizedlist><listitem><para>
 1.15863 +#: ../en/ch14-hgext.xml:33
 1.15864 +msgid ""
 1.15865 +"The Mercurial Queues patch management extension is so invaluable that it "
 1.15866 +"merits two chapters and an appendix all to itself. Chapter <xref linkend="
 1.15867 +"\"chap.mq\"/> covers the basics; chapter <xref linkend=\"chap.mq-collab\"/> "
 1.15868 +"discusses advanced topics; and appendix <xref linkend=\"chap.mqref\"/> goes "
 1.15869 +"into detail on each command."
 1.15870 +msgstr ""
 1.15871 +
 1.15872 +#. type: Content of: <book><chapter><para>
 1.15873 +#: ../en/ch14-hgext.xml:43
 1.15874 +msgid ""
 1.15875 +"In this chapter, we'll cover some of the other extensions that are available "
 1.15876 +"for Mercurial, and briefly touch on some of the machinery you'll need to know "
 1.15877 +"about if you want to write an extension of your own."
 1.15878 +msgstr ""
 1.15879 +
 1.15880 +#. type: Content of: <book><chapter><itemizedlist><listitem><para>
 1.15881 +#: ../en/ch14-hgext.xml:48
 1.15882 +msgid ""
 1.15883 +"In section <xref linkend=\"sec.hgext.inotify\"/>, we'll discuss the "
 1.15884 +"possibility of <emphasis>huge</emphasis> performance improvements using the "
 1.15885 +"<literal role=\"hg-ext\">inotify</literal> extension."
 1.15886 +msgstr ""
 1.15887 +
 1.15888 +#. type: Content of: <book><chapter><sect1><title>
 1.15889 +#: ../en/ch14-hgext.xml:55
 1.15890 +msgid ""
 1.15891 +"Improve performance with the <literal role=\"hg-ext\">inotify</literal> "
 1.15892 +"extension"
 1.15893 +msgstr ""
 1.15894 +
 1.15895 +#. type: Content of: <book><chapter><sect1><para>
 1.15896 +#: ../en/ch14-hgext.xml:58
 1.15897 +msgid ""
 1.15898 +"Are you interested in having some of the most common Mercurial operations run "
 1.15899 +"as much as a hundred times faster? Read on!"
 1.15900 +msgstr ""
 1.15901 +
 1.15902 +#. type: Content of: <book><chapter><sect1><para>
 1.15903 +#: ../en/ch14-hgext.xml:62
 1.15904 +msgid ""
 1.15905 +"Mercurial has great performance under normal circumstances.  For example, "
 1.15906 +"when you run the <command role=\"hg-cmd\">hg status</command> command, "
 1.15907 +"Mercurial has to scan almost every directory and file in your repository so "
 1.15908 +"that it can display file status.  Many other Mercurial commands need to do "
 1.15909 +"the same work behind the scenes; for example, the <command role=\"hg-cmd\">hg "
 1.15910 +"diff</command> command uses the status machinery to avoid doing an expensive "
 1.15911 +"comparison operation on files that obviously haven't changed."
 1.15912 +msgstr ""
 1.15913 +
 1.15914 +#. type: Content of: <book><chapter><sect1><para>
 1.15915 +#: ../en/ch14-hgext.xml:72
 1.15916 +msgid ""
 1.15917 +"Because obtaining file status is crucial to good performance, the authors of "
 1.15918 +"Mercurial have optimised this code to within an inch of its life.  However, "
 1.15919 +"there's no avoiding the fact that when you run <command role=\"hg-cmd\">hg "
 1.15920 +"status</command>, Mercurial is going to have to perform at least one "
 1.15921 +"expensive system call for each managed file to determine whether it's changed "
 1.15922 +"since the last time Mercurial checked.  For a sufficiently large repository, "
 1.15923 +"this can take a long time."
 1.15924 +msgstr ""
 1.15925 +
 1.15926 +#. type: Content of: <book><chapter><sect1><para>
 1.15927 +#: ../en/ch14-hgext.xml:82
 1.15928 +msgid ""
 1.15929 +"To put a number on the magnitude of this effect, I created a repository "
 1.15930 +"containing 150,000 managed files.  I timed <command role=\"hg-cmd\">hg "
 1.15931 +"status</command> as taking ten seconds to run, even when <emphasis>none</"
 1.15932 +"emphasis> of those files had been modified."
 1.15933 +msgstr ""
 1.15934 +
 1.15935 +#. type: Content of: <book><chapter><sect1><para>
 1.15936 +#: ../en/ch14-hgext.xml:88
 1.15937 +msgid ""
 1.15938 +"Many modern operating systems contain a file notification facility. If a "
 1.15939 +"program signs up to an appropriate service, the operating system will notify "
 1.15940 +"it every time a file of interest is created, modified, or deleted.  On Linux "
 1.15941 +"systems, the kernel component that does this is called <literal>inotify</"
 1.15942 +"literal>."
 1.15943 +msgstr ""
 1.15944 +
 1.15945 +#. type: Content of: <book><chapter><sect1><para>
 1.15946 +#: ../en/ch14-hgext.xml:95
 1.15947 +msgid ""
 1.15948 +"Mercurial's <literal role=\"hg-ext\">inotify</literal> extension talks to the "
 1.15949 +"kernel's <literal>inotify</literal> component to optimise <command role=\"hg-"
 1.15950 +"cmd\">hg status</command> commands.  The extension has two components.  A "
 1.15951 +"daemon sits in the background and receives notifications from the "
 1.15952 +"<literal>inotify</literal> subsystem.  It also listens for connections from a "
 1.15953 +"regular Mercurial command.  The extension modifies Mercurial's behaviour so "
 1.15954 +"that instead of scanning the filesystem, it queries the daemon.  Since the "
 1.15955 +"daemon has perfect information about the state of the repository, it can "
 1.15956 +"respond with a result instantaneously, avoiding the need to scan every "
 1.15957 +"directory and file in the repository."
 1.15958 +msgstr ""
 1.15959 +
 1.15960 +#. type: Content of: <book><chapter><sect1><para>
 1.15961 +#: ../en/ch14-hgext.xml:108
 1.15962 +msgid ""
 1.15963 +"Recall the ten seconds that I measured plain Mercurial as taking to run "
 1.15964 +"<command role=\"hg-cmd\">hg status</command> on a 150,000 file repository.  "
 1.15965 +"With the <literal role=\"hg-ext\">inotify</literal> extension enabled, the "
 1.15966 +"time dropped to 0.1 seconds, a factor of <emphasis>one hundred</emphasis> "
 1.15967 +"faster."
 1.15968 +msgstr ""
 1.15969 +
 1.15970 +#. type: Content of: <book><chapter><sect1><para>
 1.15971 +#: ../en/ch14-hgext.xml:115
 1.15972 +msgid "Before we continue, please pay attention to some caveats."
 1.15973 +msgstr ""
 1.15974 +
 1.15975 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15976 +#: ../en/ch14-hgext.xml:118
 1.15977 +msgid ""
 1.15978 +"The <literal role=\"hg-ext\">inotify</literal> extension is Linux-specific.  "
 1.15979 +"Because it interfaces directly to the Linux kernel's <literal>inotify</"
 1.15980 +"literal> subsystem, it does not work on other operating systems."
 1.15981 +msgstr ""
 1.15982 +
 1.15983 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15984 +#: ../en/ch14-hgext.xml:123
 1.15985 +msgid ""
 1.15986 +"It should work on any Linux distribution that was released after early 2005.  "
 1.15987 +"Older distributions are likely to have a kernel that lacks <literal>inotify</"
 1.15988 +"literal>, or a version of <literal>glibc</literal> that does not have the "
 1.15989 +"necessary interfacing support."
 1.15990 +msgstr ""
 1.15991 +
 1.15992 +#. type: Content of: <book><chapter><sect1><itemizedlist><listitem><para>
 1.15993 +#: ../en/ch14-hgext.xml:130
 1.15994 +msgid ""
 1.15995 +"Not all filesystems are suitable for use with the <literal role=\"hg-ext"
 1.15996 +"\">inotify</literal> extension.  Network filesystems such as NFS are a non-"
 1.15997 +"starter, for example, particularly if you're running Mercurial on several "
 1.15998 +"systems, all mounting the same network filesystem.  The kernel's "
 1.15999 +"<literal>inotify</literal> system has no way of knowing about changes made on "
 1.16000 +"another system.  Most local filesystems (e.g. ext3, XFS, ReiserFS) should "
 1.16001 +"work fine."
 1.16002 +msgstr ""
 1.16003 +
 1.16004 +#. type: Content of: <book><chapter><sect1><para>
 1.16005 +#: ../en/ch14-hgext.xml:141
 1.16006 +msgid ""
 1.16007 +"The <literal role=\"hg-ext\">inotify</literal> extension is not yet shipped "
 1.16008 +"with Mercurial as of May 2007, so it's a little more involved to set up than "
 1.16009 +"other extensions.  But the performance improvement is worth it!"
 1.16010 +msgstr ""
 1.16011 +
 1.16012 +#. type: Content of: <book><chapter><sect1><para>
 1.16013 +#: ../en/ch14-hgext.xml:146
 1.16014 +msgid ""
 1.16015 +"The extension currently comes in two parts: a set of patches to the Mercurial "
 1.16016 +"source code, and a library of Python bindings to the <literal>inotify</"
 1.16017 +"literal> subsystem."
 1.16018 +msgstr ""
 1.16019 +
 1.16020 +#. type: Content of: <book><chapter><sect1><note><para>
 1.16021 +#: ../en/ch14-hgext.xml:150
 1.16022 +msgid ""
 1.16023 +"There are <emphasis>two</emphasis> Python <literal>inotify</literal> binding "
 1.16024 +"libraries.  One of them is called <literal>pyinotify</literal>, and is "
 1.16025 +"packaged by some Linux distributions as <literal>python-inotify</literal>.  "
 1.16026 +"This is <emphasis>not</emphasis> the one you'll need, as it is too buggy and "
 1.16027 +"inefficient to be practical."
 1.16028 +msgstr ""
 1.16029 +
 1.16030 +#. type: Content of: <book><chapter><sect1><para>
 1.16031 +#: ../en/ch14-hgext.xml:157
 1.16032 +msgid ""
 1.16033 +"To get going, it's best to already have a functioning copy of Mercurial "
 1.16034 +"installed."
 1.16035 +msgstr ""
 1.16036 +
 1.16037 +#. type: Content of: <book><chapter><sect1><note><para>
 1.16038 +#: ../en/ch14-hgext.xml:160
 1.16039 +msgid ""
 1.16040 +"If you follow the instructions below, you'll be <emphasis>replacing</"
 1.16041 +"emphasis> and overwriting any existing installation of Mercurial that you "
 1.16042 +"might already have, using the latest <quote>bleeding edge</quote> Mercurial "
 1.16043 +"code. Don't say you weren't warned!"
 1.16044 +msgstr ""
 1.16045 +
 1.16046 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.16047 +#: ../en/ch14-hgext.xml:167
 1.16048 +msgid ""
 1.16049 +"Clone the Python <literal>inotify</literal> binding repository.  Build and "
 1.16050 +"install it."
 1.16051 +msgstr ""
 1.16052 +
 1.16053 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.16054 +#: ../en/ch14-hgext.xml:175
 1.16055 +msgid ""
 1.16056 +"Clone the <filename class=\"directory\">crew</filename> Mercurial "
 1.16057 +"repository.  Clone the <literal role=\"hg-ext\">inotify</literal> patch "
 1.16058 +"repository so that Mercurial Queues will be able to apply patches to your "
 1.16059 +"cope of the <filename class=\"directory\">crew</filename> repository."
 1.16060 +msgstr ""
 1.16061 +
 1.16062 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.16063 +#: ../en/ch14-hgext.xml:188
 1.16064 +msgid ""
 1.16065 +"Make sure that you have the Mercurial Queues extension, <literal role=\"hg-ext"
 1.16066 +"\">mq</literal>, enabled.  If you've never used MQ, read section <xref "
 1.16067 +"linkend=\"sec.mq.start\"/> to get started quickly."
 1.16068 +msgstr ""
 1.16069 +
 1.16070 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.16071 +#: ../en/ch14-hgext.xml:194
 1.16072 +msgid ""
 1.16073 +"Go into the <filename class=\"directory\">inotify</filename> repo, and apply "
 1.16074 +"all of the <literal role=\"hg-ext\">inotify</literal> patches using the "
 1.16075 +"<option role=\"hg-ext-mq-cmd-qpush-opt\">hg -a</option> option to the "
 1.16076 +"<command role=\"hg-ext-mq\">qpush</command> command."
 1.16077 +msgstr ""
 1.16078 +
 1.16079 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.16080 +#: ../en/ch14-hgext.xml:204
 1.16081 +msgid ""
 1.16082 +"If you get an error message from <command role=\"hg-ext-mq\">qpush</command>, "
 1.16083 +"you should not continue.  Instead, ask for help."
 1.16084 +msgstr ""
 1.16085 +
 1.16086 +#. type: Content of: <book><chapter><sect1><orderedlist><listitem><para>
 1.16087 +#: ../en/ch14-hgext.xml:208
 1.16088 +msgid "Build and install the patched version of Mercurial."
 1.16089 +msgstr ""
 1.16090 +
 1.16091 +#. type: Content of: <book><chapter><sect1><para>
 1.16092 +#: ../en/ch14-hgext.xml:216
 1.16093 +msgid ""
 1.16094 +"Once you've build a suitably patched version of Mercurial, all you need to do "
 1.16095 +"to enable the <literal role=\"hg-ext\">inotify</literal> extension is add an "
 1.16096 +"entry to your <filename role=\"special\"> /.hgrc</filename>."
 1.16097 +msgstr ""
 1.16098 +
 1.16099 +#. type: Content of: <book><chapter><sect1><para>
 1.16100 +#: ../en/ch14-hgext.xml:221
 1.16101 +msgid ""
 1.16102 +"When the <literal role=\"hg-ext\">inotify</literal> extension is enabled, "
 1.16103 +"Mercurial will automatically and transparently start the status daemon the "
 1.16104 +"first time you run a command that needs status in a repository.  It runs one "
 1.16105 +"status daemon per repository."
 1.16106 +msgstr ""
 1.16107 +
 1.16108 +#. type: Content of: <book><chapter><sect1><para>
 1.16109 +#: ../en/ch14-hgext.xml:227
 1.16110 +msgid ""
 1.16111 +"The status daemon is started silently, and runs in the background.  If you "
 1.16112 +"look at a list of running processes after you've enabled the <literal role="
 1.16113 +"\"hg-ext\">inotify</literal> extension and run a few commands in different "
 1.16114 +"repositories, you'll thus see a few <literal>hg</literal> processes sitting "
 1.16115 +"around, waiting for updates from the kernel and queries from Mercurial."
 1.16116 +msgstr ""
 1.16117 +
 1.16118 +#. type: Content of: <book><chapter><sect1><para>
 1.16119 +#: ../en/ch14-hgext.xml:235
 1.16120 +msgid ""
 1.16121 +"The first time you run a Mercurial command in a repository when you have the "
 1.16122 +"<literal role=\"hg-ext\">inotify</literal> extension enabled, it will run "
 1.16123 +"with about the same performance as a normal Mercurial command.  This is "
 1.16124 +"because the status daemon needs to perform a normal status scan so that it "
 1.16125 +"has a baseline against which to apply later updates from the kernel.  "
 1.16126 +"However, <emphasis>every</emphasis> subsequent command that does any kind of "
 1.16127 +"status check should be noticeably faster on repositories of even fairly "
 1.16128 +"modest size.  Better yet, the bigger your repository is, the greater a "
 1.16129 +"performance advantage you'll see.  The <literal role=\"hg-ext\">inotify</"
 1.16130 +"literal> daemon makes status operations almost instantaneous on repositories "
 1.16131 +"of all sizes!"
 1.16132 +msgstr ""
 1.16133 +
 1.16134 +#. type: Content of: <book><chapter><sect1><para>
 1.16135 +#: ../en/ch14-hgext.xml:249
 1.16136 +msgid ""
 1.16137 +"If you like, you can manually start a status daemon using the <command role="
 1.16138 +"\"hg-ext-inotify\">inserve</command> command.  This gives you slightly finer "
 1.16139 +"control over how the daemon ought to run.  This command will of course only "
 1.16140 +"be available when the <literal role=\"hg-ext\">inotify</literal> extension is "
 1.16141 +"enabled."
 1.16142 +msgstr ""
 1.16143 +
 1.16144 +#. type: Content of: <book><chapter><sect1><para>
 1.16145 +#: ../en/ch14-hgext.xml:256
 1.16146 +msgid ""
 1.16147 +"When you're using the <literal role=\"hg-ext\">inotify</literal> extension, "
 1.16148 +"you should notice <emphasis>no difference at all</emphasis> in Mercurial's "
 1.16149 +"behaviour, with the sole exception of status-related commands running a whole "
 1.16150 +"lot faster than they used to.  You should specifically expect that commands "
 1.16151 +"will not print different output; neither should they give different results. "
 1.16152 +"If either of these situations occurs, please report a bug."
 1.16153 +msgstr ""
 1.16154 +
 1.16155 +#. type: Content of: <book><chapter><sect1><title>
 1.16156 +#: ../en/ch14-hgext.xml:267
 1.16157 +msgid ""
 1.16158 +"Flexible diff support with the <literal role=\"hg-ext\">extdiff</literal> "
 1.16159 +"extension"
 1.16160 +msgstr ""
 1.16161 +
 1.16162 +#. type: Content of: <book><chapter><sect1><para>
 1.16163 +#: ../en/ch14-hgext.xml:270
 1.16164 +msgid ""
 1.16165 +"Mercurial's built-in <command role=\"hg-cmd\">hg diff</command> command "
 1.16166 +"outputs plaintext unified diffs."
 1.16167 +msgstr ""
 1.16168 +"Mercurial 内置命令 <command role=\"hg-cmd\">hg diff</command> 的输出与统一差异"
 1.16169 +"不同。"
 1.16170 +
 1.16171 +#. type: Content of: <book><chapter><sect1><para>
 1.16172 +#: ../en/ch14-hgext.xml:275
 1.16173 +msgid ""
 1.16174 +"If you would like to use an external tool to display modifications, you'll "
 1.16175 +"want to use the <literal role=\"hg-ext\">extdiff</literal> extension.  This "
 1.16176 +"will let you use, for example, a graphical diff tool."
 1.16177 +msgstr ""
 1.16178 +
 1.16179 +#. type: Content of: <book><chapter><sect1><para>
 1.16180 +#: ../en/ch14-hgext.xml:280
 1.16181 +msgid ""
 1.16182 +"The <literal role=\"hg-ext\">extdiff</literal> extension is bundled with "
 1.16183 +"Mercurial, so it's easy to set up.  In the <literal role=\"rc-extensions"
 1.16184 +"\">extensions</literal> section of your <filename role=\"special\"> /.hgrc</"
 1.16185 +"filename>, simply add a one-line entry to enable the extension."
 1.16186 +msgstr ""
 1.16187 +
 1.16188 +#. type: Content of: <book><chapter><sect1><para>
 1.16189 +#: ../en/ch14-hgext.xml:286
 1.16190 +msgid ""
 1.16191 +"This introduces a command named <command role=\"hg-ext-extdiff\">extdiff</"
 1.16192 +"command>, which by default uses your system's <command>diff</command> command "
 1.16193 +"to generate a unified diff in the same form as the built-in <command role="
 1.16194 +"\"hg-cmd\">hg diff</command> command."
 1.16195 +msgstr ""
 1.16196 +
 1.16197 +#. type: Content of: <book><chapter><sect1><para>
 1.16198 +#: ../en/ch14-hgext.xml:294
 1.16199 +msgid ""
 1.16200 +"The result won't be exactly the same as with the built-in <command role=\"hg-"
 1.16201 +"cmd\">hg diff</command> variations, because the output of <command>diff</"
 1.16202 +"command> varies from one system to another, even when passed the same options."
 1.16203 +msgstr ""
 1.16204 +
 1.16205 +#. type: Content of: <book><chapter><sect1><para>
 1.16206 +#: ../en/ch14-hgext.xml:299
 1.16207 +msgid ""
 1.16208 +"As the <quote><literal>making snapshot</literal></quote> lines of output "
 1.16209 +"above imply, the <command role=\"hg-ext-extdiff\">extdiff</command> command "
 1.16210 +"works by creating two snapshots of your source tree.  The first snapshot is "
 1.16211 +"of the source revision; the second, of the target revision or working "
 1.16212 +"directory.  The <command role=\"hg-ext-extdiff\">extdiff</command> command "
 1.16213 +"generates these snapshots in a temporary directory, passes the name of each "
 1.16214 +"directory to an external diff viewer, then deletes the temporary directory.  "
 1.16215 +"For efficiency, it only snapshots the directories and files that have changed "
 1.16216 +"between the two revisions."
 1.16217 +msgstr ""
 1.16218 +
 1.16219 +#. type: Content of: <book><chapter><sect1><para>
 1.16220 +#: ../en/ch14-hgext.xml:312
 1.16221 +msgid ""
 1.16222 +"Snapshot directory names have the same base name as your repository. If your "
 1.16223 +"repository path is <filename class=\"directory\">/quux/bar/foo</filename>, "
 1.16224 +"then <filename class=\"directory\">foo</filename> will be the name of each "
 1.16225 +"snapshot directory.  Each snapshot directory name has its changeset ID "
 1.16226 +"appended, if appropriate.  If a snapshot is of revision "
 1.16227 +"<literal>a631aca1083f</literal>, the directory will be named <filename class="
 1.16228 +"\"directory\">foo.a631aca1083f</filename>.  A snapshot of the working "
 1.16229 +"directory won't have a changeset ID appended, so it would just be <filename "
 1.16230 +"class=\"directory\">foo</filename> in this example.  To see what this looks "
 1.16231 +"like in practice, look again at the <command role=\"hg-ext-extdiff\">extdiff</"
 1.16232 +"command> example above.  Notice that the diff has the snapshot directory "
 1.16233 +"names embedded in its header."
 1.16234 +msgstr ""
 1.16235 +
 1.16236 +#. type: Content of: <book><chapter><sect1><para>
 1.16237 +#: ../en/ch14-hgext.xml:328
 1.16238 +msgid ""
 1.16239 +"The <command role=\"hg-ext-extdiff\">extdiff</command> command accepts two "
 1.16240 +"important options. The <option role=\"hg-ext-extdiff-cmd-extdiff-opt\">hg -p</"
 1.16241 +"option> option lets you choose a program to view differences with, instead of "
 1.16242 +"<command>diff</command>.  With the <option role=\"hg-ext-extdiff-cmd-extdiff-"
 1.16243 +"opt\">hg -o</option> option, you can change the options that <command role="
 1.16244 +"\"hg-ext-extdiff\">extdiff</command> passes to the program (by default, these "
 1.16245 +"options are <quote><literal>-Npru</literal></quote>, which only make sense if "
 1.16246 +"you're running <command>diff</command>).  In other respects, the <command "
 1.16247 +"role=\"hg-ext-extdiff\">extdiff</command> command acts similarly to the built-"
 1.16248 +"in <command role=\"hg-cmd\">hg diff</command> command: you use the same "
 1.16249 +"option names, syntax, and arguments to specify the revisions you want, the "
 1.16250 +"files you want, and so on."
 1.16251 +msgstr ""
 1.16252 +
 1.16253 +#
 1.16254 +#. type: Content of: <book><chapter><sect1><para>
 1.16255 +#: ../en/ch14-hgext.xml:345
 1.16256 +msgid ""
 1.16257 +"As an example, here's how to run the normal system <command>diff</command> "
 1.16258 +"command, getting it to generate context diffs (using the <option role=\"cmd-"
 1.16259 +"opt-diff\">-c</option> option)  instead of unified diffs, and five lines of "
 1.16260 +"context instead of the default three (passing <literal>5</literal> as the "
 1.16261 +"argument to the <option role=\"cmd-opt-diff\">-C</option> option)."
 1.16262 +msgstr ""
 1.16263 +
 1.16264 +#. type: Content of: <book><chapter><sect1><para>
 1.16265 +#: ../en/ch14-hgext.xml:354
 1.16266 +msgid ""
 1.16267 +"Launching a visual diff tool is just as easy.  Here's how to launch the "
 1.16268 +"<command>kdiff3</command> viewer."
 1.16269 +msgstr ""
 1.16270 +
 1.16271 +#. type: Content of: <book><chapter><sect1><para>
 1.16272 +#: ../en/ch14-hgext.xml:358
 1.16273 +msgid ""
 1.16274 +"If your diff viewing command can't deal with directories, you can easily work "
 1.16275 +"around this with a little scripting.  For an example of such scripting in "
 1.16276 +"action with the <literal role=\"hg-ext\">mq</literal> extension and the "
 1.16277 +"<command>interdiff</command> command, see section <xref linkend=\"mq-collab."
 1.16278 +"tips.interdiff\"/>."
 1.16279 +msgstr ""
 1.16280 +
 1.16281 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.16282 +#: ../en/ch14-hgext.xml:366
 1.16283 +msgid "Defining command aliases"
 1.16284 +msgstr ""
 1.16285 +
 1.16286 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.16287 +#: ../en/ch14-hgext.xml:368
 1.16288 +msgid ""
 1.16289 +"It can be cumbersome to remember the options to both the <command role=\"hg-"
 1.16290 +"ext-extdiff\">extdiff</command> command and the diff viewer you want to use, "
 1.16291 +"so the <literal role=\"hg-ext\">extdiff</literal> extension lets you define "
 1.16292 +"<emphasis>new</emphasis> commands that will invoke your diff viewer with "
 1.16293 +"exactly the right options."
 1.16294 +msgstr ""
 1.16295 +
 1.16296 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.16297 +#: ../en/ch14-hgext.xml:375
 1.16298 +msgid ""
 1.16299 +"All you need to do is edit your <filename role=\"special\"> /.hgrc</"
 1.16300 +"filename>, and add a section named <literal role=\"rc-extdiff\">extdiff</"
 1.16301 +"literal>.  Inside this section, you can define multiple commands.  Here's how "
 1.16302 +"to add a <literal>kdiff3</literal> command.  Once you've defined this, you "
 1.16303 +"can type <quote><literal>hg kdiff3</literal></quote> and the <literal role="
 1.16304 +"\"hg-ext\">extdiff</literal> extension will run <command>kdiff3</command> for "
 1.16305 +"you."
 1.16306 +msgstr ""
 1.16307 +
 1.16308 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.16309 +#: ../en/ch14-hgext.xml:384
 1.16310 +msgid ""
 1.16311 +"If you leave the right hand side of the definition empty, as above, the "
 1.16312 +"<literal role=\"hg-ext\">extdiff</literal> extension uses the name of the "
 1.16313 +"command you defined as the name of the external program to run.  But these "
 1.16314 +"names don't have to be the same.  Here, we define a command named "
 1.16315 +"<quote><literal>hg wibble</literal></quote>, which runs <command>kdiff3</"
 1.16316 +"command>."
 1.16317 +msgstr ""
 1.16318 +
 1.16319 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.16320 +#: ../en/ch14-hgext.xml:393
 1.16321 +msgid ""
 1.16322 +"You can also specify the default options that you want to invoke your diff "
 1.16323 +"viewing program with.  The prefix to use is <quote><literal>opts.</literal></"
 1.16324 +"quote>, followed by the name of the command to which the options apply.  This "
 1.16325 +"example defines a <quote><literal>hg vimdiff</literal></quote> command that "
 1.16326 +"runs the <command>vim</command> editor's <literal>DirDiff</literal> extension."
 1.16327 +msgstr ""
 1.16328 +
 1.16329 +#. type: Content of: <book><chapter><sect1><title>
 1.16330 +#: ../en/ch14-hgext.xml:406
 1.16331 +msgid ""
 1.16332 +"Cherrypicking changes with the <literal role=\"hg-ext\">transplant</literal> "
 1.16333 +"extension"
 1.16334 +msgstr ""
 1.16335 +
 1.16336 +#. type: Content of: <book><chapter><sect1><para>
 1.16337 +#: ../en/ch14-hgext.xml:409
 1.16338 +msgid "Need to have a long chat with Brendan about this."
 1.16339 +msgstr ""
 1.16340 +
 1.16341 +#. type: Content of: <book><chapter><sect1><title>
 1.16342 +#: ../en/ch14-hgext.xml:413
 1.16343 +msgid ""
 1.16344 +"Send changes via email with the <literal role=\"hg-ext\">patchbomb</literal> "
 1.16345 +"extension"
 1.16346 +msgstr ""
 1.16347 +
 1.16348 +#. type: Content of: <book><chapter><sect1><para>
 1.16349 +#: ../en/ch14-hgext.xml:416
 1.16350 +msgid ""
 1.16351 +"Many projects have a culture of <quote>change review</quote>, in which people "
 1.16352 +"send their modifications to a mailing list for others to read and comment on "
 1.16353 +"before they commit the final version to a shared repository.  Some projects "
 1.16354 +"have people who act as gatekeepers; they apply changes from other people to a "
 1.16355 +"repository to which those others don't have access."
 1.16356 +msgstr ""
 1.16357 +
 1.16358 +#. type: Content of: <book><chapter><sect1><para>
 1.16359 +#: ../en/ch14-hgext.xml:424
 1.16360 +msgid ""
 1.16361 +"Mercurial makes it easy to send changes over email for review or application, "
 1.16362 +"via its <literal role=\"hg-ext\">patchbomb</literal> extension.  The "
 1.16363 +"extension is so named because changes are formatted as patches, and it's "
 1.16364 +"usual to send one changeset per email message.  Sending a long series of "
 1.16365 +"changes by email is thus much like <quote>bombing</quote> the recipient's "
 1.16366 +"inbox, hence <quote>patchbomb</quote>."
 1.16367 +msgstr ""
 1.16368 +
 1.16369 +#. type: Content of: <book><chapter><sect1><para>
 1.16370 +#: ../en/ch14-hgext.xml:432
 1.16371 +msgid ""
 1.16372 +"As usual, the basic configuration of the <literal role=\"hg-ext\">patchbomb</"
 1.16373 +"literal> extension takes just one or two lines in your <filename role="
 1.16374 +"\"special\"> /.hgrc</filename>."
 1.16375 +msgstr ""
 1.16376 +
 1.16377 +#. type: Content of: <book><chapter><sect1><para>
 1.16378 +#: ../en/ch14-hgext.xml:437
 1.16379 +msgid ""
 1.16380 +"Once you've enabled the extension, you will have a new command available, "
 1.16381 +"named <command role=\"hg-ext-patchbomb\">email</command>."
 1.16382 +msgstr ""
 1.16383 +
 1.16384 +#. type: Content of: <book><chapter><sect1><para>
 1.16385 +#: ../en/ch14-hgext.xml:441
 1.16386 +msgid ""
 1.16387 +"The safest and best way to invoke the <command role=\"hg-ext-patchbomb"
 1.16388 +"\">email</command> command is to <emphasis>always</emphasis> run it first "
 1.16389 +"with the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -n</option> "
 1.16390 +"option.  This will show you what the command <emphasis>would</emphasis> send, "
 1.16391 +"without actually sending anything.  Once you've had a quick glance over the "
 1.16392 +"changes and verified that you are sending the right ones, you can rerun the "
 1.16393 +"same command, with the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -n</"
 1.16394 +"option> option removed."
 1.16395 +msgstr ""
 1.16396 +
 1.16397 +#. type: Content of: <book><chapter><sect1><para>
 1.16398 +#: ../en/ch14-hgext.xml:452
 1.16399 +msgid ""
 1.16400 +"The <command role=\"hg-ext-patchbomb\">email</command> command accepts the "
 1.16401 +"same kind of revision syntax as every other Mercurial command.  For example, "
 1.16402 +"this command will send every revision between 7 and <literal>tip</literal>, "
 1.16403 +"inclusive."
 1.16404 +msgstr ""
 1.16405 +
 1.16406 +#. type: Content of: <book><chapter><sect1><para>
 1.16407 +#: ../en/ch14-hgext.xml:457
 1.16408 +msgid ""
 1.16409 +"You can also specify a <emphasis>repository</emphasis> to compare with.  If "
 1.16410 +"you provide a repository but no revisions, the <command role=\"hg-ext-"
 1.16411 +"patchbomb\">email</command> command will send all revisions in the local "
 1.16412 +"repository that are not present in the remote repository.  If you "
 1.16413 +"additionally specify revisions or a branch name (the latter using the <option "
 1.16414 +"role=\"hg-ext-patchbomb-cmd-email-opt\">hg -b</option> option), this will "
 1.16415 +"constrain the revisions sent."
 1.16416 +msgstr ""
 1.16417 +
 1.16418 +#. type: Content of: <book><chapter><sect1><para>
 1.16419 +#: ../en/ch14-hgext.xml:466
 1.16420 +msgid ""
 1.16421 +"It's perfectly safe to run the <command role=\"hg-ext-patchbomb\">email</"
 1.16422 +"command> command without the names of the people you want to send to: if you "
 1.16423 +"do this, it will just prompt you for those values interactively.  (If you're "
 1.16424 +"using a Linux or Unix-like system, you should have enhanced "
 1.16425 +"<literal>readline</literal>-style editing capabilities when entering those "
 1.16426 +"headers, too, which is useful.)"
 1.16427 +msgstr ""
 1.16428 +
 1.16429 +#. type: Content of: <book><chapter><sect1><para>
 1.16430 +#: ../en/ch14-hgext.xml:474
 1.16431 +msgid ""
 1.16432 +"When you are sending just one revision, the <command role=\"hg-ext-patchbomb"
 1.16433 +"\">email</command> command will by default use the first line of the "
 1.16434 +"changeset description as the subject of the single email message it sends."
 1.16435 +msgstr ""
 1.16436 +
 1.16437 +#. type: Content of: <book><chapter><sect1><para>
 1.16438 +#: ../en/ch14-hgext.xml:479
 1.16439 +msgid ""
 1.16440 +"If you send multiple revisions, the <command role=\"hg-ext-patchbomb\">email</"
 1.16441 +"command> command will usually send one message per changeset.  It will "
 1.16442 +"preface the series with an introductory message, in which you should describe "
 1.16443 +"the purpose of the series of changes you're sending."
 1.16444 +msgstr ""
 1.16445 +
 1.16446 +#. type: Content of: <book><chapter><sect1><sect2><title>
 1.16447 +#: ../en/ch14-hgext.xml:486
 1.16448 +msgid "Changing the behaviour of patchbombs"
 1.16449 +msgstr ""
 1.16450 +
 1.16451 +#. type: Content of: <book><chapter><sect1><sect2><para>
 1.16452 +#: ../en/ch14-hgext.xml:488
 1.16453 +msgid ""
 1.16454 +"Not every project has exactly the same conventions for sending changes in "
 1.16455 +"email; the <literal role=\"hg-ext\">patchbomb</literal> extension tries to "
 1.16456 +"accommodate a number of variations through command line options."
 1.16457 +msgstr ""
 1.16458 +
 1.16459 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.16460 +#: ../en/ch14-hgext.xml:494
 1.16461 +msgid ""
 1.16462 +"You can write a subject for the introductory message on the command line "
 1.16463 +"using the <option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -s</option> "
 1.16464 +"option.  This takes one argument, the text of the subject to use."
 1.16465 +msgstr ""
 1.16466 +
 1.16467 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.16468 +#: ../en/ch14-hgext.xml:500
 1.16469 +msgid ""
 1.16470 +"To change the email address from which the messages originate, use the "
 1.16471 +"<option role=\"hg-ext-patchbomb-cmd-email-opt\">hg -f</option> option.  This "
 1.16472 +"takes one argument, the email address to use."
 1.16473 +msgstr ""
 1.16474 +
 1.16475 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.16476 +#: ../en/ch14-hgext.xml:506
 1.16477 +msgid ""
 1.16478 +"The default behaviour is to send unified diffs (see section <xref linkend="
 1.16479 +"\"sec.mq.patch\"/> for a description of the format), one per message.  You "
 1.16480 +"can send a binary bundle instead with the <option role=\"hg-ext-patchbomb-cmd-"
 1.16481 +"email-opt\">hg -b</option> option."
 1.16482 +msgstr ""
 1.16483 +
 1.16484 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.16485 +#: ../en/ch14-hgext.xml:514
 1.16486 +msgid ""
 1.16487 +"Unified diffs are normally prefaced with a metadata header.  You can omit "
 1.16488 +"this, and send unadorned diffs, with the <option role=\"hg-ext-patchbomb-cmd-"
 1.16489 +"email-opt\">hg --plain</option> option."
 1.16490 +msgstr ""
 1.16491 +
 1.16492 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.16493 +#: ../en/ch14-hgext.xml:520
 1.16494 +msgid ""
 1.16495 +"Diffs are normally sent <quote>inline</quote>, in the same body part as the "
 1.16496 +"description of a patch.  This makes it easiest for the largest number of "
 1.16497 +"readers to quote and respond to parts of a diff, as some mail clients will "
 1.16498 +"only quote the first MIME body part in a message. If you'd prefer to send the "
 1.16499 +"description and the diff in separate body parts, use the <option role=\"hg-"
 1.16500 +"ext-patchbomb-cmd-email-opt\">hg -a</option> option."
 1.16501 +msgstr ""
 1.16502 +
 1.16503 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.16504 +#: ../en/ch14-hgext.xml:530
 1.16505 +msgid ""
 1.16506 +"Instead of sending mail messages, you can write them to an <literal>mbox</"
 1.16507 +"literal>-format mail folder using the <option role=\"hg-ext-patchbomb-cmd-"
 1.16508 +"email-opt\">hg -m</option> option.  That option takes one argument, the name "
 1.16509 +"of the file to write to."
 1.16510 +msgstr ""
 1.16511 +
 1.16512 +#. type: Content of: <book><chapter><sect1><sect2><itemizedlist><listitem><para>
 1.16513 +#: ../en/ch14-hgext.xml:537
 1.16514 +msgid ""
 1.16515 +"If you would like to add a <command>diffstat</command>-format summary to each "
 1.16516 +"patch, and one to the introductory message, use the <option role=\"hg-ext-"
 1.16517 +"patchbomb-cmd-email-opt\">hg -d</option> option.  The <command>diffstat</"
 1.16518 +"command> command displays a table containing the name of each file patched, "
 1.16519 +"the number of lines affected, and a histogram showing how much each file is "
 1.16520 +"modified.  This gives readers a qualitative glance at how complex a patch is."
 1.16521 +msgstr ""